home *** CD-ROM | disk | FTP | other *** search
/ isnet Internet / Isnet Internet CD.iso / prog / chat / 20 / 20.exe / vscript.txt < prev    next >
Encoding:
Text File  |  1997-09-01  |  143.9 KB  |  4,101 lines
  1. ViRCScript Documentation (for Visual IRC '97 1.00 and above) - Revision 20
  2. ==========================================================================
  3.  
  4. This is the documentation for ViRCScript, ViRC '97's advanced scripting
  5. language. At over 4000 lines long, this is one heavyweight document!! This is
  6. not intended as an introduction to IRC commands or to programming languages in
  7. general. Rather, it is for people who wish to use ViRCScript to extend the
  8. functionality of ViRC '97 in any way imaginable.
  9.  
  10. If you are having scripting problems, the people on EFnet #virc will be glad to
  11. help, although please try to read this file thoroughly first!!
  12.  
  13. Features new in this release of ViRCScript are marked with an * in the index.
  14.  
  15. Index
  16. =====
  17.  
  18. [1.0] Introduction
  19.   [1.1] What's new in this release of ViRCScript?
  20.   [1.2] Syntax (read this ;)
  21.   [1.3] Variables
  22.   [1.4] Variables within variables (don't necessarily read this ;)
  23. [2.0] ViRCScript language reference
  24.   [2.1] Flow control statements
  25.     [2.1.1] If/Else/EndIf
  26.     [2.1.2] For/EndFor
  27.     [2.1.3] ForEach/EndForEach *
  28.     [2.1.4] Switch/Case/EndSwitch *
  29.       [2.1.3.1] Expr directive *
  30.       [2.1.3.2] Is directive *
  31.       [2.1.3.3] Matches directive *
  32.       [2.1.3.4] Multi directive *
  33.       [2.1.3.5] Range directive *
  34.     [2.1.4] While/EndWhile
  35.   [2.2] Alias/event/menu definition statements
  36.     [2.2.1] Alias/EndAlias
  37.     [2.2.2] Event/EndEvent
  38.     [2.2.3] MenuTree/EndMenuTree
  39.     [2.2.4] MenuItem/EndMenuItem
  40.   [2.3] Parsing statements
  41.     [2.3.1] Parse/EndParse (obsolete - use list-handling functions instead)
  42.   [2.4] Commands
  43.     [2.4.1] Formatted text output commands
  44.       [2.4.1.1] FlushBitmapCache *
  45.       [2.4.1.2] TextOut
  46.       [2.4.1.3] TextOutBitmap *
  47.     [2.4.2] Flow control commands
  48.       [2.4.2.1] Break
  49.       [2.4.2.2] Continue
  50.       [2.4.2.4] FallThrough
  51.       [2.4.2.3] Halt
  52.       [2.4.2.5] Yield
  53.     [2.4.3] Alias/event/menu control commands
  54.       [2.4.3.1] DisableEvent
  55.       [2.4.3.2] EnableEvent
  56.       [2.4.3.3] FireEvent
  57.       [2.4.3.4] SetAlias
  58.       [2.4.3.5] UnAlias
  59.       [2.4.3.6] UnEvent
  60.       [2.4.3.7] UpdateMenus
  61.     [2.4.4] Window manipulation commands
  62.       [2.4.4.1] Close
  63.       [2.4.4.2] Max
  64.       [2.4.4.3] Min
  65.       [2.4.4.4] Restore
  66.       [2.4.4.5] SetFocus
  67.     [2.4.5] File I/O commands
  68.       [2.4.5.2] AppendText
  69.       [2.4.5.1] CreateFile
  70.       [2.4.5.5] ChDir
  71.       [2.4.5.4] MkDir
  72.       [2.4.5.6] RmDir
  73.       [2.4.5.3] RmFile
  74.     [2.4.6] Registry I/O commands
  75.       [2.4.6.1] RehashRegistry
  76.       [2.4.6.2] WriteRegistry
  77.     [2.4.7] Sound and multimedia commands
  78.       [2.4.7.1] Beep
  79.       [2.4.7.2] MCI
  80.     [2.4.8] Server (and IRC) commands
  81.       [2.4.8.1] Say
  82.       [2.4.8.2] ASay
  83.       [2.4.8.3] AMe
  84.       [2.4.8.4] SimulateServerData
  85.       [2.4.8.5] Using regular IRC commands
  86.     [2.4.9] Inter-server communication commands
  87.       [2.4.9.1] OnServer *
  88.     [2.4.10] Miscellaneous commands
  89.       [2.4.10.1] AcceptDCC *
  90.       [2.4.10.2] AddToIAL *
  91.       [2.4.10.3] CancelDCC *
  92.       [2.4.10.4] DDE
  93.       [2.4.10.5] DisableInternalXDCCEvents *
  94.       [2.4.10.6] DNS
  95.       [2.4.10.7] EnableInternalXDCCEvents *
  96.       [2.4.10.8] Eval
  97.       [2.4.10.9] Name
  98.       [2.4.10.10] NoAttribs
  99.       [2.4.10.11] MessageBox
  100.       [2.4.10.12] SetInputLine
  101.       [2.4.10.13] UserAdd
  102.       [2.4.10.14] UserDelete
  103.       [2.4.10.15] UserDeleteWithWildcards
  104.     [2.4.11] Debugging commands
  105.       [2.4.11.1] EvaluateWindow
  106.   [2.5] Functions
  107.     [2.5.1] String manipulation functions
  108.       [2.5.1.1] Asc
  109.       [2.5.1.2] Char
  110.       [2.5.1.3] IsNumeric *
  111.       [2.5.1.4] IsChannel *
  112.       [2.5.1.5] IsURL *
  113.       [2.5.1.6] Length
  114.       [2.5.1.7] Lower
  115.       [2.5.1.8] MaskMatch
  116.       [2.5.1.9] RStrPos
  117.       [2.5.1.10] RStrTokL
  118.       [2.5.1.11] RStrTokR
  119.       [2.5.1.12] StrPos
  120.       [2.5.1.13] StrPosFrom
  121.       [2.5.1.14] StrTokL
  122.       [2.5.1.15] StrTokR
  123.       [2.5.1.16] StrTrim
  124.       [2.5.1.17] SubStr
  125.       [2.5.1.18] Upper
  126.       [2.5.1.19] WildMatch
  127.       [2.5.1.20] WordCount
  128.     [2.5.2] List manipulation functions
  129.       [2.5.2.1] listElementCount *
  130.       [2.5.2.2] listIndex *
  131.       [2.5.2.3] listIndexOf *
  132.       [2.5.2.4] listInsert *
  133.       [2.5.2.5] listJoin *
  134.       [2.5.2.6] listRange *
  135.       [2.5.2.7] listRemove *
  136.       [2.5.2.8] listReplace *
  137.       [2.5.2.9] listSearch *
  138.       [2.5.2.10] listSearchReplace *
  139.       [2.5.2.11] listSplit *
  140.     [2.5.3] Set manipulation functions
  141.       [2.5.3.1] IsInSet
  142.       [2.5.3.2] AddToSet
  143.       [2.5.3.3] RemoveFromSet
  144.     [2.5.4] Alias/event manipulation functions
  145.       [2.5.4.1] AliasExists
  146.       [2.5.4.2] EventExists
  147.       [2.5.4.3] IsEventEnabled
  148.     [2.5.5] Formatted text output functions
  149.       [2.5.5.1] Bitmap *
  150.     [2.5.6] Time and clock functions
  151.       [2.5.6.1] CTime
  152.       [2.5.6.2] Date
  153.       [2.5.6.3] DecodeInterval
  154.       [2.5.6.4] DecodePingInterval
  155.       [2.5.6.5] IdleMTime
  156.       [2.5.6.6] IdleTime
  157.       [2.5.6.7] MTime
  158.       [2.5.6.8] Time
  159.       [2.5.6.9] TimeConnected
  160.       [2.5.6.10] UnixTime
  161.     [2.5.7] File I/O functions
  162.       [2.5.7.1] FileExists
  163.       [2.5.7.2] GetCurrentDir
  164.       [2.5.7.3] GetFileDateTime
  165.       [2.5.7.4] GetFileSize
  166.       [2.5.7.5] GetLinesInFile
  167.       [2.5.7.6] GetPath
  168.       [2.5.7.7] PathExists
  169.       [2.5.7.8] RandomRead
  170.       [2.5.7.9] ReadLine
  171.     [2.5.8] Registry I/O functions
  172.       [2.5.8.1] ReadRegistry
  173.       [2.5.8.2] GetSetting
  174.     [2.5.9] Common dialogs
  175.       [2.5.9.1] OpenDialog
  176.       [2.5.9.2] OpenPictureDialog *
  177.       [2.5.9.3] SaveDialog
  178.       [2.5.9.4] SavePictureDialog *
  179.     [2.5.10] IRC-specific functions
  180.       [2.5.10.1] ActiveWindow
  181.       [2.5.10.2] ChannelCount
  182.       [2.5.10.3] Channels
  183.       [2.5.10.4] ChannelList *
  184.       [2.5.10.5] CurrentServer_ActiveWindow
  185.       [2.5.10.6] GetAddress
  186.       [2.5.10.7] GetBanLevel
  187.       [2.5.10.8] GetCustomLevel *
  188.       [2.5.10.9] GetLag
  189.       [2.5.10.10] GetUser
  190.       [2.5.10.11] GetUserLevel
  191.       [2.5.10.12] GetProtLevel
  192.       [2.5.10.13] IsDCCChatting
  193.       [2.5.10.14] IsOn
  194.       [2.5.10.15] IsOp
  195.       [2.5.10.16] IsQuerying
  196.       [2.5.10.17] IsVoice *
  197.       [2.5.10.18] IsWatchdogActive
  198.       [2.5.10.19] Nicks
  199.       [2.5.10.20] NickCount
  200.       [2.5.10.21] NickList *
  201.       [2.5.10.22] Ops
  202.       [2.5.10.23] OpCount
  203.       [2.5.10.24] OpList *
  204.       [2.5.10.25] OpStrip
  205.       [2.5.10.26] Peons
  206.       [2.5.10.27] PeonCount
  207.       [2.5.10.28] PeonList *
  208.       [2.5.10.29] QueryList *
  209.       [2.5.10.30] SelectedNick
  210.       [2.5.10.31] VoiceList *
  211.     [2.5.11] XDCC (file offer server) functions
  212.       [2.5.11.1] GetXDCCPackCount
  213.       [2.5.11.2] GetXDCCPackDesc
  214.       [2.5.11.3] GetXDCCPackFileCount
  215.       [2.5.11.4] GetXDCCPackFiles
  216.       [2.5.11.5] GetXDCCPackGets
  217.       [2.5.11.6] GetXDCCPackSize
  218.     [2.5.12] DCC (chat and file transfer) functions
  219.       [2.5.12.1] DCCChatList *
  220.       [2.5.12.2] DCCGetList *
  221.       [2.5.12.3] DCCSendList *
  222.       [2.5.12.4] GetDCCSize *
  223.       [2.5.12.5] GetDCCSpeed *
  224.       [2.5.12.6] GetDCCPercent *
  225.       [2.5.12.7] GetDCCProgress *
  226.       [2.5.12.8] GetDCCTimeLeft *
  227.     [2.5.13] Inter-server communication functions
  228.       [2.5.13.1] CurrentServer *
  229.       [2.5.13.2] ServerCount *
  230.       [2.5.13.3] ServerList *
  231.     [2.5.14] Miscellaneous functions
  232.       [2.5.14.1] $? (text input dialog)
  233.       [2.5.14.2] DecodeIP
  234.       [2.5.14.3] DNS
  235.       [2.5.14.4] EncodeIP
  236.       [2.5.14.5] GetAlias
  237.       [2.5.14.6] GetInputLine
  238.       [2.5.14.7] GetWindowID
  239.       [2.5.14.8] MessageDlg
  240.       [2.5.14.9] Rand
  241.  
  242. [1.0] Introduction
  243. ==================
  244.  
  245. What is ViRCScript? ViRCScript (from now on abbreviated to VS) is the scripting
  246. language supported by ViRC '97. VS is similar to BASIC, C, VPL, and ircII's
  247. scripting language. You use VS to write code for events and aliases. In 1.00rc1,
  248. the ViRCScript interpreter is around 99% complete. Newer versions will add more
  249. functionality, however, I will endeavour to ensure that these new changes don't
  250. break your old code.
  251.  
  252. VS is 100% written by myself. I've used no code from anywhere else or custom
  253. controls in my parser, numerical evaluator, or anything else. This means that
  254. if you have any problems, you have no-one to blame them on but me. >:-> (That
  255. said, no-one has reported any real problems in ViRCScript. It seems to be the
  256. most stable portion of V97 I've written so far).
  257.  
  258. [1.1] What's new in this release of ViRCScript?
  259. -----------------------------------------------
  260.  
  261. Note that this list also includes the stuff new in 0.80, 0.82 and 0.82a.
  262.  
  263. The ^^ (raise to a power) operator now works properly. Deleting array variables
  264. with a variable as the index (e.g. -@ $array.$x) now works properly
  265. (finally!! ;). Added C-style += and -= operators. Added date/time formatting
  266. capabilities to the TIME function. Corrected some documentation inaccuracies
  267. (e.g. the built-in variables, and in the sample code for the IDLETIME
  268. function). New built-in <OnNewInactiveText> event. New BEEP command. New
  269. OPENDIALOG and SAVEDIALOG functions to encapsulate the common dialogs. Fixed
  270. bugs where pseudovariables could be lost after TextOut and Yield statements.
  271. New built-in DCC events (<OnDCCChatConnect>, <OnDCCChatText>,
  272. <OnDCCChatDisconnect>). Minor performance improvements. HALT statement now
  273. breaks out of all loops correctly (previous versions had problems with breaking
  274. out of nested code blocks). MIN, MAX, RESTORE, CLOSE, SETFOCUS window-handling
  275. functions. New file I/O stuff (READLINE, GETLINESINFILE commands). Directory
  276. I/O stuff (MKDIR, CHDIR, RMDIR commands, GETCURRENTDIR function). UNALIAS and
  277. UNEVENT commands added. ObjectViRCScript extensions added (see OBJECTVS.TXT).
  278. New MESSAGEDLG function added.
  279.  
  280. New in 0.82: SIMULATESERVERDATA command. New OPTIMIZED keyword for FOR and
  281. WHILE statements. New set-handling functions (ADDTOSET, REMOVEFROMSET and
  282. ISINSET). New ALIASEXISTS and EVENTEXISTS functions. New GETUSER function.
  283. Documented event templates (they were implemented in 0.80, but were documented
  284. only in 0.82). Severely-broken BREAK command fixed. CONTINUE command added.
  285. Conditional execution parameters added to BREAK and HALT commands (and CONTINUE
  286. too). Corrected documentation inaccuracies (e.g. the code sample given in the
  287. local variables section (the LOCALTEST and LOCALLOOP aliases) did not work at
  288. all ;). New OPSTRIP and SELECTEDNICK functions.
  289.  
  290. New in 0.82a: Buggy string comparisons with == fixed. WILDMATCH function
  291. improved to handle a*c-style wildcards. New === (exactly equals) operator
  292. added.
  293.  
  294. New in 0.91: Completely rewritten parser - should now be around 5x faster.
  295. However, there is a _VERY_ small chance that some of your old scripts
  296. (especially if they are badly written) will break. If this occurs let me know
  297. and I'll see what I can do. New modulus (%) operator added. New WORDCOUNT
  298. function. New SETALIAS command to set the contents of an alias from a variable.
  299. Corresponding new GETALIAS function. New READREGISTRY function and
  300. WRITEREGISTRY command. New GETXDCCPACKCOUNT, GETXDCCPACKSIZE, GETXDCCPACKGETS,
  301. GETXDCCPACKDESC, GETXDCCPACKFILES, and GETXDCCPACKFILECOUNT functions. New
  302. GETWINDOWID function. New UNIXTIME function. New DECODEIP function. Added
  303. bitwise XOR operator (^) to be compatible with C. Old && and || operators were
  304. really bitwise and not comparative, and so failed sometimes, so I made them
  305. comparative and added the bitwise & and | operators which correspond to the old
  306. && and ||. VS now supports an indentical lot of operators to C. New GETFILESIZE
  307. and GETFILEDATETIME functions. Local array variables now supported. Made !=
  308. case-insensitive and made new !== operator for case-sensitive comparisons. New
  309. DISABLEEVENT and ENABLEEVENT commands. New PATHEXISTS function. New
  310. ISEVENTENABLED function.
  311.  
  312. New in 0.92: Rewritten script loading code - large scripts now load in 5
  313. seconds, rather than 5 minutes. Added new STRPOSFROM function. New
  314. EVALUATEWINDOW command for debugging. New STRTOKL and STRTOKR functions. RMFILE
  315. (added ages ago) finally documented. New RSTRPOS, RSTRTOKL and RSTRTOKR
  316. functions. New NOATTRIBS command. EVAL command can now be called as a function.
  317.  
  318. New in 0.92b: DNS function added to perform a DNS lookup.
  319.  
  320. New in 0.94pre8: ISNUMERIC function added. SWITCH statement added. TCL-like
  321. lists added. FOREACH statement added. New LISTREMOVE TCL-like list function.
  322. Added CASE ELSE to SWITCH statement.
  323.  
  324. New in 0.94pre10c: New LISTINDEXOF TCL-like list function. New CANCELDCC and
  325. ACCEPTDCC statements. Many problems with SWITCH/CASE statements fixed.
  326.  
  327. New in 1.00rc1: New \k attribute code for doing mIRC colours easily. Documented
  328. assignment of variables within variables.
  329.  
  330. New in 1.00rc4: Added OPENPICTUREDIALOG and SAVEPICTUREDIALOG functions.
  331.  
  332. New in 1.00rc5: Greatly extended functionality of SWITCH/CASE. Added bitshift
  333. operators (<< and >>).
  334.  
  335. New in 1.00rc5b: The GETFILESIZE function now returns -1 if the file doesn't
  336. exist or cannot be accessed, instead of 0.
  337.  
  338. New in 1.00rc6: Added new DCCCHATLIST, DCCGETLIST, DCCSENDLIST, GETDCCSIZE,
  339. GETDCCSPEED, GETDCCPROGRESS, GETDCCPOSITION and GETDCCTIMELEFT functions.
  340. ACCEPTDCC command now accepts a filename as a parameter.
  341.  
  342. New in 1.00rc6b: Added new ONSERVER command and SERVERLIST, SERVERCOUNT and
  343. CURRENTSERVER function. Added new \o and \r attributes. Added support for
  344. query window popups (MT_QueryTextPopup) and corrected a number of documentation
  345. inaccuracies in VSCRIPT.TXT (including documentation errors in the MenuTree and
  346. MenuItem statements).
  347.  
  348. New in 1.00almost-final2: Added new GETCUSTOMLEVEL function. ISVOICE and
  349. VOICELIST functions and the USERADD command are now documented.
  350.  
  351. New in 1.00almost-final3b: Added new ADDTOIAL command. Added new USERDELETE and
  352. USERDELETEBYMASK commands.
  353.  
  354. [1.2] Syntax
  355. ------------
  356.  
  357. Place one VS instruction on each line. Lines beginning with # or // are assumed
  358. to be comments, and are ignored. Otherwise the line is parsed and executed.
  359. Statements and functions are case-insensitive, except for variables, which are
  360. case-sensitive, i.e. $x is not the same as $X. Numerical parameters to
  361. functions can be supplied in decimal, or in hex by prefixing with a $. For
  362. example, to get a random number between 0 and 254, you could use:
  363.  
  364.         $rand(255)
  365.  
  366.     Or:
  367.  
  368.         $rand($FF)
  369.  
  370. [1.3] Variables
  371. ---------------
  372.  
  373. Variables are allocated and assigned with the @ operator, and deallocated with
  374. the -@ operator. Examples:
  375.  
  376.         @ $x = Hello everybody!!
  377.         -@ $x
  378.  
  379. Wildcards are supported when using -@, and this is very useful with arrays.
  380. Say, for example, you defined the following array:
  381.  
  382.         @ $greeting.0 = Hello
  383.         @ $greeting.1 = Hi
  384.         @ $greeting.2 = Yo
  385.         @ $greeting.3 = Greetings
  386.         @ $greeting.4 = Howdy
  387.  
  388. You could delete the whole thing in one go with the single statement:
  389.  
  390.         -@ $greeting.*
  391.  
  392. Or, as the array element numbers are only 1 figure long:
  393.  
  394.         -@ $greeting.?
  395.  
  396. You should always deallocate used variables at the end of your scripts, as
  397. "dangling" variables will make script parsing slower and take up memory.
  398.  
  399. In addition, ViRC '97 0.34 and above support stored variables. These are like
  400. regular variables, except their values are stored in the registry, and hence
  401. are retained if V97 is closed down and then restarted. Define a stored
  402. variable exactly like a regular variable, except use @s instead of @. Undefine
  403. a stored variable by using -@s instead of -@. For example:
  404.  
  405.         @s $script_ver = YTooLZ for ViRC '97 version 4.91
  406.  
  407. The value of $script_ver will not be lost when V97 is closed down.
  408.  
  409. The third type of variable (new in V96 0.80) is the local variable. This type
  410. of variable is the recommended type to use inside your aliases and events.
  411. Local variables are only accessible from the scope that they were created in.
  412. In addition, you can have more than one local variable with the same name,
  413. provided they are in different scope blocks. ViRC '97's garbage collector
  414. automatically deallocates local variables when they fall out of scope - you
  415. cannot deallocate them yourself. Local variables are created with @l instead of
  416. @. V96 0.91 and above support local array variables, too. Simple example:
  417.  
  418.         @l $x = hello
  419.  
  420. Here's a good example of where global (@) variables will not work, and you have
  421. to use locals. Just type /localtest, and observe the (correct, expected)
  422. output:
  423.  
  424. Alias LOCALTEST
  425.   for (@l $i = 0; $i < 10; $i++)
  426.     TextOut > . clBlue Variable $$i in LOCALTEST: $i
  427.     LocalLoop
  428.   endfor
  429. EndAlias
  430.  
  431. Alias LOCALLOOP
  432.   for (@l $i = 0; $i < 10; $i++)
  433.     TextOut > . clBlue Variable $$i in LOCALLOOP: $i
  434.   endfor
  435. EndAlias
  436.  
  437. This code will work correctly, despite the fact that two local variables called
  438. $i are used at the same time, as they are defined as local (@l) variables. If
  439. the @l was changed to @ to make them global variables, typing /localtest would
  440. produce incorrect output as the $i defined in LOCALTEST would be accessible in
  441. LOCALLOOP.
  442.  
  443. Bear in mind speed considerations when using the different types of variables.
  444. Local variables (e.g. @l $x = 0) are the fastest. Global variables (e.g.
  445. @ $x = 0) are almost, but not quite, as fast as local variables. Local array
  446. variables (e.g. @l $x.0 = 0) and global array variables (e.g. @ $x.0 = 0) are
  447. much slower, so don't use them heavily in tight loops! (that said, they're not
  448. _that_ slow ... even a slow PC should have no problem executing several
  449. thousand complex array operations every second).
  450.  
  451. You can evaluate a numeric expression by enclosing it in $( and ). For example:
  452.  
  453.         @ $x = $(1+1)
  454.  
  455. As opposed to @ $x = 1+1, which will assign the string "1+1" to the variable
  456. $x, and so _WILL_NOT_WORK_.
  457.  
  458. You can evaluate expressions as complex as you want, including variables and
  459. functions, for example:
  460.  
  461.         @ $x = $((((16/2)*$strpos(xt $3-))+(18/$dfactor))-1)
  462.  
  463. $() is not required in if/while/for statements, as the conditions are evaluated
  464. numerically anyway.
  465.  
  466. In addition, V96 0.60 and above support the C-style ++ and -- operators. What's
  467. more, they're not just a pretty face - they execute a LOT, LOT faster than the
  468. equivalent code @ $i = $($i + 1), and are ideal for loops and things. For
  469. example, to increment $x by one, you could use:
  470.  
  471.         $x++
  472.  
  473. Please note that, unlike variable assignments, you DO NOT prefix this with an
  474. @. V96 0.80 and above support the C-style += and -= operators (BUT NOT *= and
  475. /= etc. yet), e.g.
  476.  
  477.         $x += 4
  478.         $y -= 16
  479.  
  480. Again, these are much faster than the equivalent @ $x = $($x + 4) etc.
  481. ViRCScript doesn't care about spacing when using any of these operators.
  482.  
  483. Pseudovariables (Pvars) are also supported in aliases and events. A typical
  484. Pvar looks like $0, or $7-, and represents a parameter supplied to the alias or
  485. event. $n means the n'th parameter. With events, the first word of the line of
  486. text received from the server is $0, the second word $1, and so on. With
  487. aliases, the alias command is $0, the first parameter supplied is $1, the
  488. second parameter supplied is $2, and so on. In addition, an expression like
  489. $2- means "the second parameter and all subsequent parameters". So, $2- is
  490. equal to $2 $3 $4 $5 $6 $7 $8 .... $n. More about this later.
  491.  
  492. V97 also maintains a number of built-in variables. These are as follows:
  493.  
  494.         $ver    The current version of V97, e.g. 0.60
  495.         $build  The current version V97 in integer form, e.g. 60
  496.         $N      Your nickname
  497.         $U      Your username
  498.         $H      Your hostname
  499.         $ip     Your IP address
  500.         $server The server you're connected to
  501.         $C      The channel the user types the alias in. If the alias
  502.                 is typed in a server window, $C is set to . (a period).
  503.                 If the alias is typed in a query window, $C contains the
  504.                 nick of the person you are querying.
  505.         $null   Equals nothing. Use to set variables to nothing, e.g.
  506.                 @ $x = $null
  507.  
  508. A number of constants are also maintained:
  509.  
  510.         \b      Bold
  511.         \u      Underline
  512.         \i      Italic
  513.         \o      Clear bold, underline and italic attributes (does NOT clear
  514.                 mIRC colour and reverse video)
  515.         \r      Reverse video (interchange background and foreground colours
  516.                 of text)
  517.         \k      mIRC colour (format is \kFOREGROUND,BACKGROUND, e.g. \k1,9 is
  518.                 black text on a yellow background)
  519.         \A      ASCII character 1 -  (used for CTCPs), also used for web
  520.                 hyperlinks (e.g. \Ahttp://click-here.com\A)
  521.         \t      Tab character (a certain number of spaces, as set in Client
  522.                 setup/ViRC '97 options/Text output settings)
  523.  
  524. Note that V97 supports a number of simultaneous server connections, even if
  525. you're on the same channel on both servers!! And you can have a different
  526. nickname on each server. So what nickname does $N correspond to? The answer is,
  527. the active context's nickname. If you use $N from an event, $N is the nickname
  528. on the server which caused the event. $N in an alias refers to the nickname of
  529. the current server connection relating to the window you typed the alias in.
  530. For example, $N in a channel window would be your nick on the server that
  531. you're on that channel on. Sounds confusing? Just use $N and it should work as
  532. you expect it to every time. =]
  533.  
  534. What about $+ you may ask. As most of you know, in mIRC, PIRCH etc. you need
  535. $+ to trim spaces ... in other words, you'd need something like this:
  536.  
  537.         *** $nick ( $+ $user $+ @ $+ $host $+ ) has joined channel $3
  538.  
  539. To display this:
  540.  
  541.         *** MeGALiTH (megalith@jimc.demon.co.uk) has joined channel #quake
  542.  
  543. In V97, spaces are not required before variables and functions, because of its
  544. intelligent parser. So you could do something like this, which looks much
  545. neater:
  546.  
  547.         *** $nick ($user@$host) has joined channel $3
  548.  
  549. The above would totally foul up mIRC and PIRCH. In fact, V97 doesn't care what
  550. you have before or after a variable. This would work:
  551.  
  552.         alkjdsjkadjka$nickjhdakajsdakjdhkjadhk
  553.  
  554. So, the skeptic asks, in this case, how does V97 know whether you want the
  555. variable $nick, $nickj, $nickjhdak, or what? The answer is, it reads your mind.
  556. Well, almost ... the new parser takes care of it in a different, and rather
  557. more complex way, than the old one ... but it should work properly every time.
  558.  
  559. [1.4] Variables within variables
  560. --------------------------------
  561.  
  562. In V96 0.91 and later, VS supports variables within variables. This is achieved
  563. with the new $'$var' syntax. It's best demonstrated as follows:
  564.  
  565.         @ $blah = hello
  566.         @ $foo = blah
  567.  
  568.         TextOut > . clBlue $'$foo'
  569.  
  570. This will print hello on the screen. $'$foo' basically means "the value of the
  571. variable whose name is the value of $foo". So $'$foo' means the value of
  572. the variable whose name is $blah, which is hello.
  573.  
  574. You can also assign variables within variables in a similar way. For example:
  575.  
  576.         @ $blah = hello
  577.         @ $'$blah' = goodbye
  578.  
  579. This would assign goodbye to the variable $hello.
  580.  
  581. If this doesn't make any sense, email me and let me know!!
  582.  
  583. [2.0] ViRCScript language reference
  584. ===================================
  585.  
  586. [2.1] Flow control statements
  587. -----------------------------
  588.  
  589. [2.1.1] If/Else/EndIf statements
  590. --------------------------------
  591.  
  592. Usage: if (condition)
  593.           ...
  594.        [else]
  595.           [...]
  596.        endif
  597.  
  598. Executes a block of code only if a given condition is true. Multiple conditions
  599. can be specified, and are separated with && (boolean AND) or || (boolean OR)
  600. operators. If the condition is false and an ELSE block exists, this code is
  601. executed. The following operators are supported:
  602.  
  603.         Op  | Meaning
  604.       ------+--------------------------
  605.         ==  | Equal to (case-insensitive)
  606.         === | Equal to (same as == only case-sensitive when comparing strings)
  607.         !=  | Not equal to (case-insensitive)
  608.         !== | Not equal to (case-sensitive)
  609.         >   | Greater than
  610.         <   | Less than
  611.         >=  | Greater than or equal to
  612.         <=  | Less than or equal to
  613.         &&  | Boolean AND
  614.         ||  | Boolean OR
  615.         !   | Boolean NOT
  616.         +   | Plus
  617.         -   | Minus
  618.         *   | Multiply
  619.         /   | Divide
  620.         %   | Modulus (remainder after division)
  621.         ^^  | Power
  622.         &   | Bitwise AND
  623.         |   | Bitwise OR
  624.         ^   | Bitwise XOR
  625.         <<  | Bitshift left
  626.         >>  | Bitshift right
  627.  
  628. If you're used to C, you'll have no problems. Expressions can be as simple or
  629. as complex as you like - you can nest many levels of brackets if you need to.
  630.  
  631. IF can be used to compare numeric expressions or string expressions. All string
  632. expressions must be enclosed in []'s, just as in ircII.
  633.  
  634. Numeric expression example:
  635.  
  636.         if (2+3 == 5)
  637.            TextOut clBlue Of course it does!!
  638.         endif
  639.  
  640. String expression example:
  641.  
  642.         if ([hello] == [goodbye])
  643.            TextOut clBlue Not unless the laws of physics have changed.
  644.         endif
  645.  
  646. Boolean operators may also be used. && = and, || = or, ! = not.
  647.  
  648.         if (2+3 == 5) && (4*2 == 8)
  649.            TextOut clBlue Naturally.
  650.         endif
  651.  
  652. In fact, you'll rarely have to use the ! operator. You'll see that the
  653. following two statements are equivalent:
  654.  
  655.         if ([$x] != [$y])
  656.         if !([$x] == [$y])
  657.  
  658. Note that spaces are not required (they are ignored by the parser), but may be
  659. included for clarity. For example:
  660.  
  661.         if (2+3==5)&&(10*17==170)&&((5>=2)||(9==16))
  662.  
  663. That's perfectly correct, but impossible to read ;). Adding spaces makes the
  664. statement far clearer:
  665.  
  666.         if (2+3 == 5) && (10*17 == 170) && ((5 >= 2) || (9 == 16))
  667.  
  668. You must enclose string expressions in []'s. This prevents V97 from trying to
  669. numerically evaluate the text between the [ and the ]. For example:
  670.  
  671.         if ([$nick] == [hello])
  672.            TextOut clBlue Blah!!
  673.         endif
  674.  
  675. An ELSE construction is supported too.
  676.  
  677.         @ $x = $?="What does IRC stand for?"
  678.         if ([$x] == [Internet Relay Chat])
  679.            TextOut clGreen Well done!!
  680.         else
  681.            TextOut clRed Wrong!!
  682.         endif
  683.  
  684. [2.1.3] ForEach/EndForEach statements
  685. -------------------------------------
  686.  
  687. Usage: ForEach (variable;list)
  688.          ...
  689.        EndForEach
  690.  
  691.        ForEach (variable,variable,variable ... ;list)
  692.          ...
  693.        EndForEach
  694.  
  695. This statement really is every scripter's dream. Basically, it iterates through
  696. every item in list, assigning one or more elements in list to one or more of
  697. the variables specified. If one variable is specified, the code block is
  698. executed for each element (word) in list. If more than one variable is
  699. specified, then elements are assigned sequentually to each variable until all
  700. the variables have been assigned, and then the code block is executed for
  701. each group of elements in list. This sounds rather complex, however, usage is
  702. not that tricky to grasp. It's best illustrated with lots of examples:
  703.  
  704.         ForEach ($number; 1 2 3 4 5 6 7 8)
  705.           TextOut > . clBlack $number
  706.         EndForEach
  707.  
  708. This will output the following:
  709.  
  710.         1
  711.         2
  712.         3
  713.         4
  714.         5
  715.         6
  716.         7
  717.         8
  718.  
  719. As stated, more than one variable can be supplied, separated by a comma:
  720.  
  721.         ForEach ($number1, $number2; 1 2 3 4 5 6 7 8)
  722.           TextOut > . clBlack $number1 $number2
  723.         EndForEach
  724.  
  725. This will output the following:
  726.  
  727.         1 2
  728.         3 4
  729.         5 6
  730.         7 8
  731.  
  732. Some more examples of that technique:
  733.  
  734.         @l $numbers = 1 2 3 4 5 6 7 8
  735.         ForEach ($number1, $number2, $number3; $numbers)
  736.           TextOut > . clBlack $number1
  737.         EndForEach
  738.  
  739. This will output the following:
  740.  
  741.         1
  742.         4
  743.         7
  744.  
  745. Another example:
  746.  
  747.         ForEach ($number1, $number2, $number3; 1 2 3 4 5 6 7 8)
  748.           TextOut > . clBlack $number1 $number2 $number3
  749.         EndForEach
  750.  
  751. This will output the following:
  752.  
  753.         1 2 3
  754.         4 5 6
  755.         7 8
  756.  
  757. If you'd like to see more examples, or have a better description of the FOREACH
  758. statement that you'd like to share with other VS programmers, feel free to
  759. email me at foreach-request@jimc.demon.co.uk.
  760.  
  761. [2.1.3] For/EndFor statements
  762. -----------------------------
  763.  
  764. Usage: for [optimized] (initial statement;condition;increment statement)
  765.          ...
  766.        endfor
  767.  
  768. V97's for statement behaves exactly like the for statement in C/C++, so you
  769. should have no problems. For example, the following C code:
  770.  
  771.         for (int i = 0; i < 10; i++)
  772.           printf("%d", i);
  773.  
  774. Is equivalent to the following ViRCScript code:
  775.  
  776.         for (@ $i = 0; $i < 10; $i++)
  777.           TextOut clBlue $i
  778.         endfor
  779.  
  780. (Note the use of the new ++ operator here!!)
  781.  
  782. Note that variables created by the for statement (e.g. the $i above) are not
  783. deallocated at the end, so the following statement should really be added to
  784. the end of the above code fragment:
  785.  
  786.         -@ $i
  787.  
  788. The for and while statements are often interchangable. In fact:
  789.  
  790.         for (x;y;z)
  791.           ...
  792.         endfor
  793.  
  794. Is equivalent to:
  795.  
  796.         x
  797.         while (y)
  798.           ...
  799.           z
  800.         endwhile
  801.  
  802. However, usage of for is much neater in many cases than while. Note that, just
  803. like C, misuse of for can lock the system up!! Compare the following C
  804. fragment:
  805.  
  806.         for (;;)
  807.           ...
  808.  
  809. And the following ViRCScript:
  810.  
  811.         for (;;)
  812.           ...
  813.         endfor
  814.  
  815. Both will lock the system up in an infinite loop (unless, of course, a BREAK
  816. or HALT statement is used somewhere in the loop). So be careful!!
  817.  
  818. In V96 0.82 and above, the new OPTIMIZED keyword is supported. You can use it
  819. like this:
  820.  
  821. for optimized (@ $i = 1; $i <= 10000; $i++)
  822.   $j++
  823. endfor
  824.  
  825. OPTIMIZED enables specific optimizations which cause tight loops (containing
  826. only one instruction, in this case $j++) to execute around 20% faster. V97 will
  827. check that the loop contains only one instruction if you specify OPTIMIZED, and
  828. if it does not, the keyword will be ignored.
  829.  
  830. You can use all regular commands and functions in an OPTIMIZED for loop except
  831. for HALT, BREAK, FALLTHROUGH, YIELD, and TEXTOUT. Usage of these commands in an
  832. OPTIMIZED loop may cause undefined (and possibly erratic) problems.
  833.  
  834. [2.1.4] Switch/EndSwitch statements
  835. -----------------------------------
  836.  
  837. Usage: Switch x
  838.          [Case a:]
  839.            [...]
  840.          [Case Expr b]
  841.            [...]
  842.          [Case Is c]
  843.            [...]
  844.          [Case Matches d]
  845.            [...]
  846.          [Case Multi e]
  847.            [...]
  848.          [Case Range f]
  849.            [...]
  850.          [Case Else]
  851.            [...]
  852.        EndSwitch
  853.  
  854. Executes a block of code if x matches any of the cases given. If x matches none
  855. of the cases given, the code in the CASE ELSE block is executed, if present.
  856. Functionally similar to the switch statement in C. In case code blocks (...),
  857. a special variable, $@, is available, which contains the contents of the
  858. condition being tested against, x. Example:
  859.  
  860.         @l $num = $?="Enter a number from 1 to 3"
  861.         Switch $num
  862.           Case 1:
  863.             MessageBox You entered the number "one".
  864.           Case 2:
  865.             MessageBox You entered the number "two".
  866.           Case 3:
  867.             MessageBox You entered the number "three".
  868.           Case Else
  869.             MessageBox You didn't enter a number between 1 and 3!!
  870.         EndSwitch
  871.  
  872. Another example:
  873.  
  874.         @l $num = $?="Enter YES SIR or NO WAY."
  875.         Switch $num
  876.           Case YES SIR:
  877.             MessageBox You said YES SIR!
  878.           Case NO WAY:
  879.             MessageBox You said NO WAY!
  880.           Case Else
  881.             MessageBox You said $@. I told you to enter YES SIR or NO WAY. :)
  882.         EndSwitch
  883.  
  884. The CASE statement and the block of code must be on separate lines. Putting
  885. both on one line is invalid and will not work.
  886.  
  887. New in 1.00rc5 are a number of extended case directives: EXPR, IS, MULTI,
  888. MATCHES, and RANGE. This will be documented separately.
  889.  
  890. [2.1.4.1] Expr directive
  891. ------------------------
  892.  
  893. Usage: Switch x
  894.          Case Expr a
  895.            ...
  896.        EndSwitch
  897.  
  898. Executes the code block ... if the expression a is true. Use the special
  899. variable $@ to determine the condition being tested against.
  900.  
  901.         Switch $?="Enter a number between 10 and 20."
  902.           Case Expr ($@ >= 10) && ($@ <= 20)
  903.             MessageBox You entered $@.
  904.           Case Else
  905.             MessageBox You didn't enter a number between 10 and 20!!
  906.         EndSwitch
  907.  
  908. [2.1.4.2] Is directive
  909. ----------------------
  910.  
  911. Usage: Switch x
  912.          Case Is a
  913.            ...
  914.        EndSwitch
  915.  
  916. Executes the code block ... if the partial expression a is true. a is something
  917. like > 10 or < 20. Example:
  918.  
  919.         Switch $?="Enter a number."
  920.           Case Is > 100:
  921.             MessageBox The number was greater than 100.
  922.           Case Is < 100:
  923.             MessageBox The number was less than 100.
  924.           Case 100:
  925.             MessageBox The number was 100.
  926.         EndSwitch
  927.  
  928. [2.1.4.3] Matches directive
  929. ---------------------------
  930.  
  931. Usage: Switch x
  932.          Case Matches a
  933.            ...
  934.        EndSwitch
  935.  
  936. Executes the code block ... if x is matched by a, which may contain wildcard
  937. characters (* and ?). Example:
  938.  
  939.         Switch $?="Enter a word."
  940.           Case Matches *e*
  941.             MessageBox The word contains the letter e.
  942.           Case Else
  943.             MessageBox The word doesn't contain the letter e.
  944.         EndSwitch
  945.  
  946. [2.1.4.4] Multi directive
  947. -------------------------
  948.  
  949. Usage: Switch x
  950.          Case Multi a
  951.            ...
  952.          EndSwitch
  953.  
  954. Executes the code block ... if x is matched by a, which may contain a number of
  955. values, separated by commas. Take this code which does not use the Multi
  956. directive, for example:
  957.  
  958.         Switch $?="Enter 13, 17, 23 or 31."
  959.           Case 13:
  960.             MessageBox OK.
  961.           Case 17:
  962.             MessageBox OK.
  963.           Case 23:
  964.             MessageBox OK.
  965.           Case 31:
  966.             MessageBox OK.
  967.           Case Else
  968.             MessageBox You didn't enter 13, 17, 23 or 31.
  969.         EndSwitch
  970.  
  971. However, the above code could be written more efficiently, with the Multi
  972. directive, as follows:
  973.  
  974.         Switch $?="Enter 13, 17, 23 or 31."
  975.           Case Multi 13,17,23,31
  976.             MessageBox OK.
  977.           Case Else
  978.             MessageBox You didn't enter 13, 17, 23 or 31.
  979.         EndSwitch
  980.  
  981. [2.1.4.5] Range directive
  982. -------------------------
  983.  
  984. Usage: Switch x
  985.          Case Range a..b
  986.            ...
  987.        EndSwitch
  988.  
  989. Executes the code block ... if x lies in the numeric range from a to b
  990. (inclusive). Example:
  991.  
  992.         Switch $?="Enter a number."
  993.           Case Is < 0
  994.             MessageBox The number is negative.
  995.           Case 0..100
  996.             MessageBox The number is between 0 and 100 (inclusive).
  997.           Case Is > 100
  998.             MessageBox The number is greater than 100.
  999.         EndSwitch
  1000.  
  1001. [2.1.5] While/EndWhile statements
  1002. ---------------------------------
  1003.  
  1004. Usage: while [optimized] (condition)
  1005.          ...
  1006.        endwhile
  1007.  
  1008. Executes a block of code while condition is true. If condition is false
  1009. initially, the while block will be skipped. See the IF/ELSE/ENDIF statement for
  1010. details on how to specify conditions. Beware, as a condition that's always true
  1011. will produce an infinite loop and will lock V97 up!! For example:
  1012.  
  1013.         while (1)
  1014.         endwhile
  1015.  
  1016. In fact, now ViRCScript has a C-like for statement, while is largely
  1017. superflous. In fact:
  1018.  
  1019.         while (condition)
  1020.           ...
  1021.         endwhile
  1022.  
  1023. Is functionally-identical to:
  1024.  
  1025.         for (;condition;)
  1026.           ...
  1027.         endfor
  1028.  
  1029. The for statement is used only with a condition, with no initial statement and
  1030. no increment statement.
  1031.  
  1032. In V96 0.82 and above, the new OPTIMIZED keyword is supported. You can use it
  1033. like this:
  1034.  
  1035. while optimized ($i <= 10000)
  1036.   $i++
  1037. endwhile
  1038.  
  1039. OPTIMIZED enables specific optimizations which cause tight loops (containing
  1040. only one instruction, in this case $j++) to execute around 20% faster. V97 will
  1041. check that the loop contains only one instruction if you specify OPTIMIZED, and
  1042. if it does not, the keyword will be ignored.
  1043.  
  1044. You can use all regular commands and functions in an OPTIMIZED while loop
  1045. except for HALT, BREAK, CONTINUE, FALLTHROUGH, YIELD, and TEXTOUT. Usage of
  1046. these commands in an OPTIMIZED loop may cause undefined (and possibly erratic)
  1047. problems.
  1048.  
  1049. [2.2] Alias/event/menu definition statements
  1050. --------------------------------------------
  1051.  
  1052. [2.2.1] Alias/EndAlias statements
  1053. ---------------------------------
  1054.  
  1055. Usage: Alias <name> [hotkey]
  1056.          ...
  1057.        EndAlias
  1058.  
  1059. Defines an alias (similar to a procedure or function in other languages).
  1060. The parameters of the alias are passed in as $1, $2, $3 and so on, and the
  1061. actual alias command itself is passed in as $0. The channel window the alias is
  1062. typed in is passed in as $C. $C is set to . if the alias is run from the server
  1063. notices window. Optionally, hotkey may be specifed (e.g. F3, or Ctrl+Shift+Z).
  1064. When hotkey is pressed, the alias will be executed as if it were typed in the
  1065. current window.
  1066.  
  1067. It's recommended that, to begin with, you try making some aliases in ViRC '97's
  1068. alias editor (Scripting/Aliases ...), as this saves having to make text files
  1069. and then using /load to load them in. Of course, when making an alias with
  1070. V97's alias editor, you DON'T include the Alias and EndAlias lines, as the name
  1071. and hotkey for the alias have already been entered manually.
  1072.  
  1073. Aliases can be very useful, for example, consider this:
  1074.  
  1075.         Alias GO
  1076.           Connect
  1077.           Join #quake
  1078.           Msg Bot !op
  1079.           Mode #quake +ooo User1 User2 User3
  1080.           Part #quake
  1081.           Quit
  1082.         EndAlias
  1083.  
  1084. When the user types /go, V97 will connect to the server, join #quake, /msg Bot
  1085. for ops, op User1, User2 and User3, leave #quake, and quit IRC. Aliases can
  1086. also be used as functions. Simply assign a value to $fresult as the value of
  1087. the function. For example, consider this, a function to pick and return a
  1088. random boolean value, either True or False:
  1089.  
  1090.         Alias RANDBOOL
  1091.           @ $x = $rand(2)
  1092.           if ($x == 1)
  1093.              @ $fresult = True
  1094.           else
  1095.              @ $fresult = False
  1096.           endif
  1097.         EndAlias
  1098.  
  1099. Now:
  1100.  
  1101.         TextOut clBlue Random boolean expression: $randbool()
  1102.  
  1103. In V96 0.91 and above, if an alias, which is called as a function, doesn't
  1104. assign a value to $fresult, it will automatically return the string <no value>,
  1105. for example:
  1106.  
  1107.         TextOut clBlue $nonexistentfunction()
  1108.  
  1109. This will output the string:
  1110.  
  1111.         <no value>
  1112.  
  1113. Notice that, in 1.00rc5 and above, an alias can tell if it's being executed as
  1114. a command or called as a function. The name of the alias is always available
  1115. as $0, but if the alias is called as a function, $0 is prefixed by a %
  1116. character. So, you can have code like this to check if an alias is being called
  1117. as a function or not:
  1118.  
  1119.         if ([$substr($0 1 1)] == [%])
  1120.            // Called as a function (for example, $0 = %TEST) ...
  1121.         else
  1122.            // Called as a command (for example, $0 = TEST) ...
  1123.         endif
  1124.  
  1125. Another use for aliases is executing frequently-used single commands. For
  1126. example, say you're on #quake, and are frequently asked what the current
  1127. version of Quake is. You could make an alias like this:
  1128.  
  1129.         Alias QUAKEVER
  1130.           Say $C $1: The current version of Quake is 1.01.
  1131.         EndAlias
  1132.  
  1133. Then, for example, if Dnormlguy asked what the latest version of Quake was,
  1134. in the #quake channel window, you could just type /quakever Dnormlguy. V97
  1135. would expand $C to #quake, and $1 to the first parameter, Dnormlguy. So, the
  1136. text "Dnormlguy: The current version of Quake is 0.92" to the channel.
  1137.  
  1138. Newer versions of V97 (after about 0.90) don't need the $C at all, so the above
  1139. alias could be rewritten simply as:
  1140.  
  1141.         Alias QUAKEVER
  1142.           Say $1: The current version of Quake is 1.01.
  1143.         EndAlias
  1144.  
  1145. [2.2.2] Event/EndEvent statements (read!! This is changed!!)
  1146. ------------------------------------------------------------
  1147.  
  1148. Usage: Event <name> "<mask>"
  1149.          ...
  1150.        EndEvent
  1151.  
  1152. Defines an event. Events are the most powerful feature of VS, although also the
  1153. hardest to grasp (although this has largely been alleviated now that event
  1154. priorities have been removed). The best way to get a feel for events is to look
  1155. through V97's built-in events and see how they work.
  1156.  
  1157. It's recommended that, to begin with, you try making some events in ViRC '97's
  1158. event editor (Scripting/Events ...), as this saves having to make text files
  1159. and then using /load to load them in. Of course, when making an event with
  1160. V97's event editor, you DON'T include the Event and EndEvent lines, as the name
  1161. and mask for the event have already been entered manually.
  1162.  
  1163. Name is just an arbitrary name to assign to the event. You can call events
  1164. anything you like. Mask is the text that must be received from the server to
  1165. trigger the event, and can include wildcards.
  1166.  
  1167. Parameters are passed into the event with the first word received from the
  1168. server as $0, the second word as $1, etc. In addition, the sender of the
  1169. message's nick is stored in $nick, the username in $user, and the hostname
  1170. in $host. If the message originates from the server, $nick is the server, and
  1171. $user and $host are empty. Example:
  1172.  
  1173.         :greygoon!bhess@wilma.widomaker.com NOTICE MeGALiTH :You're not opped!!
  1174.  
  1175. This is what the server sends when greygoon sends the notice
  1176. "You're not opped!!" to MeGALiTH. So, the parameter breakdown would be as
  1177. follows:
  1178.  
  1179.         $0      :greygoon!bhess@wilma.widomaker.com
  1180.         $1      NOTICE
  1181.         $2      MeGALiTH
  1182.         $3      :You're
  1183.         $4      not
  1184.         $5      opped!!
  1185.  
  1186.         $nick   greygoon
  1187.         $user   bhess
  1188.         $host   wilma.widomaker.com
  1189.  
  1190. Thus the activation mask for a NOTICE is "* NOTICE *". This basically means:
  1191. $0 can be anything, $1 must be NOTICE, and $2 can be anything. Any parameters
  1192. that are not supplied can be anything - in fact, the * at the end of the mask
  1193. is not really necessary, but is included for clarity.
  1194.  
  1195. More specific masks are executed in preference to less specific masks. For
  1196. example, the following event statements are used for private and channel
  1197. messages.
  1198.  
  1199.         Private messages:
  1200.  
  1201.            Event PrivateMessage "* PRIVMSG *"
  1202.  
  1203.         Channel messages:
  1204.  
  1205.            Event ChannelMessage "* PRIVMSG #*"
  1206.  
  1207. A typical private message received from the server may look like this:
  1208.  
  1209.         :nick!user@host PRIVMSG YourNick :hello!!
  1210.  
  1211. A typical channel message might look like this:
  1212.  
  1213.         :nick!user@host PRIVMSG #quake :hello all!!
  1214.  
  1215. Therefore, if V97 gets a channel message, the PrivateMessage event is NOT
  1216. executed, even though the mask matches, because there's a more specific event
  1217. mask that matches, namely ChannelMessage.
  1218.  
  1219. Note that the <default> event (mask *), which is fired for every line of server
  1220. text that is received, is only executed if NO OTHER EVENTS have a mask which
  1221. matches the line of server text.
  1222.  
  1223. In 0.80 and above, event templates are supported. This means that you can use
  1224. masks from other events as templates for your own masks, which makes the
  1225. events clearer. You use another event mask as a template by putting the name
  1226. of the event in ()'s at the beginning of your own mask. For example, the CTCP
  1227. event mask is as follows:
  1228.  
  1229.         * PRIVMSG * :\A*
  1230.  
  1231. Therefore, if you wanted to make an event that responded to CTCP HELLO, you
  1232. could do:
  1233.  
  1234.         Event CTCPHello "(CTCP)HELLO"
  1235.  
  1236. V97 would expand the mask (CTCP)HELLO to ...
  1237.  
  1238.         * PRIVMSG * :\A*HELLO
  1239.  
  1240. ... which is the correct mask to do what you want. In addition, if you wish to
  1241. redefine an event without changing the mask, you could always use the event
  1242. mask itself as a mask template, for example:
  1243.  
  1244.         Event PrivateMessage "(PrivateMessage)"
  1245.           ... code for new PrivateMessage event ...
  1246.         EndEvent
  1247.  
  1248. Events that begin with < (with the exception of <default>) are NEVER fired by
  1249. events from the server, even if the masks match. You can thus create your own
  1250. <On_xxx> events which you can fire manually from code with the FIREEVENT
  1251. command.
  1252.  
  1253. Built-in events
  1254. ---------------
  1255.  
  1256. V97 has a number of built-in events. They are:
  1257.  
  1258.         <OnConnect> - fired when connected to a server
  1259.                       $0 = server name
  1260.  
  1261.         <OnDisconnect> - fired when disconnected from a server
  1262.                          $0 = server name
  1263.  
  1264.         <OnErrorConnecting> - fired when a socket error occurs while connecting
  1265.                               to a server (for example, connection refused)
  1266.                               $0 = error number, $1- = error message
  1267.  
  1268.         <OnNotifyJoin> - fired when a user in the notify list joins IRC
  1269.                          $0 = nick of user who joined
  1270.  
  1271.         <OnNotifyQuit> - fired when a user in the notify list leaves IRC
  1272.                          $0 = nick of user who left
  1273.  
  1274.         <OnNewInactiveText> - fired when next is added to an inactive window
  1275.                               $0 = 1 if first new line, 0 for subsequent lines
  1276.                               $1 = window type (SERVER, CHANNEL, QUERY, or DCC)
  1277.                               $2 = window name (e.g. #quake, MeGALiTH, etc).
  1278.  
  1279.         <OnDCCChatConnect> - fired when a DCC Chat session connects
  1280.                              $0 = nick of user who chat connection is with
  1281.  
  1282.         <OnDCCChatDisconnect> - fired when a DCC Chat session disconnects
  1283.                                 $0 = nick of user who chat connection is with
  1284.  
  1285.         <OnDCCSendConnect> - fired when a DCC Send session connects
  1286.                              $0 = nick of user you're sending the file to
  1287.                              $1 = filename of file you're sending
  1288.  
  1289.         <OnDCCSendDisconnect> - fired when a DCC Send session disconnects
  1290.                                 $0 = nick of user you're sending the file to
  1291.                                 $1 = filename of file you're sending
  1292.                                 $2 = 1 if transfer complete, 0 if transfer aborted
  1293.  
  1294.         <OnDCCGetConnect> - fired when a DCC Send session connects
  1295.                             $0 = nick of user you're getting the file from
  1296.                             $1 = filename of file you're receiving
  1297.  
  1298.         <OnDCCGetDisconnect> - fired when a DCC Send session disconnects
  1299.                                $0 = nick of user you're getting the file from
  1300.                                $1 = filename of file you're receiving
  1301.                                $2 = 1 if transfer complete, 0 if transfer aborted
  1302.  
  1303.         <OnAcceptDCCQuery> - fired before an incoming DCC connection is accepted
  1304.                              $nick, $user, $host, $dcctype, $dccfile, $dccip,
  1305.                              $dccport and $dccsize are available here, which
  1306.                              describe the incoming DCC connection. In this
  1307.                              event, you may execute the AcceptDCC command,
  1308.                              which accepts the DCC connection without any
  1309.                              confirmation from the user, or the CancelDCC
  1310.                              command, which will cancel the DCC connection
  1311.                              without any confirmation from the user.
  1312.  
  1313.         <OnStart>            - fired when ViRC '97 starts up
  1314.  
  1315.         <OnClose>            - fired when ViRC '97 closes down
  1316.  
  1317. IMPORTANT NOTE: In 0.82 and later versions of V97, you can define multiple,
  1318. individual events for each of the above. This is done by calling the events
  1319. <OnXXXX_text>. For example, if you wanted several <OnStart> events, you could
  1320. define them as <OnStart_1>, <OnStart_2> etc., and they would each be called
  1321. correctly. If you are defining these events in a script, it is STRONGLY
  1322. RECOMMENDED that you give these events a unique name, so that it doesn't
  1323. interfere with the operation of any other scripts, for example, you could call
  1324. an event <OnStart_XYZScript> or <OnDCCGetConnect_XYZScript> if you're writing
  1325. a script called XYZScript.
  1326.  
  1327. Event names in <>'s (e.g. <OnXYZ>) will never be fired by text received from
  1328. the server, even if the masks match. If they're not built-in events, like
  1329. <OnStart>, you will have to call them manually with the FIREEVENT command.
  1330.  
  1331. [2.2.3] MenuTree/EndMenuTree command
  1332. ------------------------------------
  1333.  
  1334. Usage: MenuTree menutype
  1335.          [item1]
  1336.          [item2]
  1337.          ...
  1338.        EndMenuTree
  1339.  
  1340. Defines the menu tree for menutype. This command is used to define the
  1341. structure of a menu or popup, before code is assigned to each item. The
  1342. following values for menutype are currently recognized:
  1343.  
  1344.      MT_MainMenu          - define the tree for the main menu
  1345.      MT_ServerPopup       - define the tree for the server window popup
  1346.      MT_ChannelTextPopup  - define the tree for the channel window text pane
  1347.                             popup
  1348.      MT_ChannelNicksPopup - define the tree for the channel window names pane
  1349.                             popup
  1350.      MT_QueryTextPopup    - define the tree for the query window text pane
  1351.                             popup
  1352.  
  1353. Each item defined between MenuTree and EndMenuTree takes the following format:
  1354.  
  1355.      ItemName HotKey State Depth Text
  1356.  
  1357. ItemName is an arbitrary name to give to the menu item. The name will be used
  1358. again later to define the code when you click on the menu item. HotKey defines
  1359. what hotkey to activate the menu item on. HotKey can be something like F12 or
  1360. Ctrl+Shift+A, or <none> if you don't require a hotkey. Note that HotKey is
  1361. ignored for menus other than MT_MainMenu. State determines the menu item's
  1362. state. For menu types MT_MainMenu and MT_ServerPopup, State can take the
  1363. following values:
  1364.  
  1365.         0 - Menu item is enabled
  1366.         1 - Menu item is enabled when you're connected to the server, and
  1367.             disabled otherwise
  1368.         2 - Menu item is disabled when you're connected to the server, and
  1369.             enabled otherwise
  1370.         3 - Menu item is disabled
  1371.  
  1372. For menu types MT_ChannelTextPopup and MT_ChannelNicksPopup, State can take the
  1373. following values:
  1374.  
  1375.         0 - Menu item is enabled
  1376.         1 - Menu item is enabled when you're opped on this channel, and
  1377.             disabled otherwise
  1378.         2 - Menu item is disabled when you're opped on this channel, and
  1379.             enabled otherwise
  1380.         3 - Menu item is disabled
  1381.  
  1382. For menu type MT_QueryTextPopup, State can take the following values:
  1383.  
  1384.         0 - Menu item is enabled
  1385.         3 - Menu item is disabled
  1386.  
  1387. Depth defines the "depth" of the menu item. For MT_MainMenu, a depth of 0
  1388. represents an entry on the top menu bar. A depth of 1 is a subitem of the
  1389. closest item above which has a depth of 0. A depth of 2 is a subitem of the
  1390. closest item above that has a depth of 1. In V97 1.00af3 and above, depths of
  1391. 3 and 4 are also supported, and these are simply subitems of the nearest items
  1392. above that have a depth of 2 and 3 respectively.
  1393.  
  1394. Text is the actual text to display on the menu. If an & is present in Text,
  1395. you can pull the menu down quickly by pressing Alt and the letter after the &.
  1396.  
  1397. Here are some example menu tree items, taken from DEFAULT.LIB:
  1398.  
  1399.   M_FILE       <none> 0 0 &File
  1400.   M_NEWCONNECT Ctrl+K 0 1 &New connection ...
  1401.   M_SETUP      <none> 0 1 Client s&etup ...
  1402.   M_FSEP1      <none> 0 1 -
  1403.   M_EXIT       Alt+X  0 1 E&xit
  1404.   M_TOOLS      <none> 0 0 &Tools
  1405.   M_FINGER     Ctrl+F 0 1 UNIX &finger ...
  1406.  
  1407. Hopefully by comparing this with what you actually see in the program will
  1408. enable you to understand the significance of each field.
  1409.  
  1410. After defining your menu trees, it is crucial to include an UpdateMenus
  1411. command to make V97 actually update the menus on-screen.
  1412.  
  1413. [2.2.4] MenuItem/EndMenuItem command
  1414. ------------------------------------
  1415.  
  1416. Usage: MenuItem ItemName on MenuType
  1417.  
  1418. Defines the ViRCScript code to trigger when the user clicks on the menu item
  1419. ItemName on the menu type MenuType. MenuType can take the same values here as
  1420. with the MenuTree command detailed above. In the above example, one of the item
  1421. lines between MenuTree and EndMenuTree is:
  1422.  
  1423.   M_NEWCONNECT Ctrl+K 0 1 &New connection ...
  1424.  
  1425. To define the ViRCScript code to actually make this open a new server window,
  1426. you would use:
  1427.  
  1428.         MenuItem M_NEWCONNECT on MT_MainMenu
  1429.           NewServerWindow
  1430.         EndMenuItem
  1431.  
  1432. For a good example of how this works, see DEFAULT.LIB.
  1433.  
  1434. Menu items on a MenuType of MT_ChannelTextPopup and MT_ChannelNicksPopup are
  1435. supplied with the current channel window as $C.
  1436.  
  1437. Menu items on a MenuType of MT_ChannelNicksPopup are supplied with the nickname
  1438. selected in the names pane of the currently-active channel window as the
  1439. parameter $nick (and also as $1). If more than one nick is selected, the first
  1440. nick selected is available as $nick (and also as $1), the second nick selected
  1441. is available as $2, the third is available as $3, and so forth. For example:
  1442.  
  1443.         MenuItem M_HELLO on MT_ChannelNicksPopup
  1444.           Say Hello, $nick!!
  1445.         EndMenuItem
  1446.  
  1447. If the user clicks on abc123's nick in a channel window, and then right-clicks
  1448. and selects M_HELLO from the popup menu, the text "Hello, abc123!!" will be
  1449. said to the channel.
  1450.  
  1451.         MenuItem M_DEMO1 on MT_ChannelNicksPopup
  1452.           Say The following nicks are selected: $1-
  1453.         EndMenuItem
  1454.  
  1455. This example will say what nicks are selected to the channel.
  1456.  
  1457. Menu items on a MenuType of MT_QueryTextPopup are supplied with the nickname
  1458. of the person you're querying as $nick.
  1459.  
  1460. [2.3] Parsing statements
  1461. ------------------------
  1462.  
  1463. [2.3.1] Parse/EndParse statements
  1464. ---------------------------------
  1465.  
  1466. Note that this feature, although still present and functional (to preserve
  1467. compatibility with old scripts), has largely been superceded by the new
  1468. list-handling functions, and as such should be considered obsolete.
  1469.  
  1470. Usage: Parse [extended] text
  1471.         ...
  1472.        EndParse
  1473.  
  1474. Parses text into the pseudovariables $0 to $9 for the duration of the parse
  1475. block. Without doubt one of the most powerful commands in ViRCScript. Its use
  1476. is best illustrated by an example:
  1477.  
  1478.         @ $x = This is a test.
  1479.         Parse $x
  1480.           TextOut clBlue $0 $1 $2 $3
  1481.           TextOut clBlue $3 $2 $1 $0
  1482.         EndParse
  1483.  
  1484. The following will appear on the screen:
  1485.  
  1486.         This is a test.
  1487.         test. a is This
  1488.  
  1489. The values of the pseudovariables are restored to their previous state at the
  1490. end of the parse block. So, they are only valid between Parse and EndParse.
  1491. You must assign them to other variables if you want to use them outside the
  1492. parse block. You may nest as many parse blocks within each other as you like.
  1493.  
  1494. What in reality could this be used for? One idea is a #chaos-type question
  1495. game, You have a file called QUESTION.TXT which contains questions and answers
  1496. in the form:
  1497.  
  1498.         answer question ...
  1499.         answer question ...
  1500.         answer question ...
  1501.  
  1502. And so on. You want some code to pick a random question from the file, putting
  1503. the question in $question and the answer in $answer. The following code would
  1504. do the trick:
  1505.  
  1506.         @ $x = $randomread(question.txt)
  1507.         Parse $x
  1508.           @ $answer = $0
  1509.           @ $question = $1-
  1510.         EndParse
  1511.  
  1512. In addition, 0.91 and above support the new EXTENDED keyword. If this keyword
  1513. is specified, multiple words surrounded by quotes will be parsed as one
  1514. parameter. Example:
  1515.  
  1516.         Parse "one two" "three four"
  1517.           TextOut > . clBlue 0: $0
  1518.           TextOut > . clBlue 1: $1
  1519.           TextOut > . clBlue 2: $2
  1520.           TextOut > . clBlue 3: $3
  1521.         EndParse
  1522.  
  1523.         Parse Extended "one two" "three four"
  1524.           TextOut > . clBlue 0: $0
  1525.           TextOut > . clBlue 1: $1
  1526.           TextOut > . clBlue 2: $2
  1527.           TextOut > . clBlue 3: $3
  1528.         EndParse
  1529.  
  1530. The first block of code will display:
  1531.  
  1532.         0: "one
  1533.         1: two"
  1534.         2: "three
  1535.         3: four"
  1536.  
  1537. The second block of code will display:
  1538.  
  1539.         0: "one two"
  1540.         1: "three four"
  1541.         2:
  1542.         3:
  1543.  
  1544. The EXTENDED keyword is very useful when you're parsing strings that might
  1545. contain multiple filenames, each enclosed in quotes (the filenames may contain
  1546. spaces on Win32 systems, remember). For example, the following code snippet
  1547. will display each filename in XDCC pack #1 on a separate line:
  1548.  
  1549.         Parse Extended $getxdccpackfiles(1)
  1550.           for (@l $i = 0; $i < $getxdccpackfilecount(1); $i++)
  1551.             TextOut > . clBlack $'$i'
  1552.           endfor
  1553.         EndParse
  1554.  
  1555. [2.4] Commands
  1556. --------------
  1557.  
  1558. [2.4.1] Formatted text output commands
  1559. --------------------------------------
  1560.  
  1561. [2.4.1.1] FlushBitmapCache statement
  1562. ------------------------------------
  1563.  
  1564. Usage: FlushBitmapCache
  1565.  
  1566. Clears V97's internal text bitmap caches. If you are using your own custom
  1567. bitmaps in text output and you change them on disk, you need to execute this
  1568. command to reload the bitmaps from disk. More information about when you need
  1569. to use this command is given in the description for the Bitmap function.
  1570.  
  1571. [2.4.1.2] TextOut statement
  1572. ---------------------------
  1573.  
  1574. Usage: TextOut [> window] <colour> <text ...>
  1575.  
  1576. Displays some text in a window. If the window name is left out, TextOut will
  1577. output the text to all channel windows, unless there are none open, in which
  1578. case the text will be displayed in the server window. Specifying a channel name
  1579. will display the text in that channel (or the server window if the channel
  1580. doesn't exist). Specifying . will output the text to the server notices window.
  1581. Specifying anything else will create a query window with that name (if it
  1582. doesn't already exist) and output the text there. You can use a query window
  1583. created "on-the-fly" like this as a simple text output window for your scripts.
  1584.  
  1585. Colour may be specified in four ways.
  1586.  
  1587.         (1) Specifying a colour constant. The following colour constants
  1588.             are supported (this will be familiar to Delphi 2.0 users):
  1589.  
  1590.             clBlack             Black
  1591.             clMaroon            Maroon
  1592.             clGreen             Green
  1593.             clOlive             Olive green
  1594.             clNavy              Navy blue
  1595.             clPurple            Purple
  1596.             clTeal              Teal
  1597.             clGray              Gray
  1598.             clSilver            Silver
  1599.             clRed               Red
  1600.             clLime              Lime green
  1601.             clBlue              Blue
  1602.             clFuchsia           Fuchsia
  1603.             clAqua              Aqua
  1604.             clWhite             White
  1605.  
  1606.             clBackground        Current color of your Windows background
  1607.             clActiveCaption     Current color of the title bar of the active window
  1608.             clInactiveCaption   Current color of the title bar of inactive windows
  1609.             clMenu              Current background color of menus
  1610.             clWindow            Current background color of windows
  1611.             clWindowFrame       Current color of window frames
  1612.             clMenuText          Current color of text on menus
  1613.             clWindowText        Current color of text in windows
  1614.             clCaptionText       Current color of the text on the title bar of the active window
  1615.             clActiveBorder      Current border color of the active window
  1616.             clInactiveBorder    Current border color of inactive windows
  1617.             clAppWorkSpace      Current color of the application workspace
  1618.             clHighlight         Current background color of selected text
  1619.             clHightlightText    Current color of selected text
  1620.             clBtnFace           Current color of a button face
  1621.             clBtnShadow         Current color of a shadow cast by a button
  1622.             clGrayText          Current color of text that is dimmed
  1623.             clBtnText           Current color of text on a button
  1624.             clInactiveCaptionText   Current color of the text on the title bar of an inactive window
  1625.             clBtnHighlight      Current color of the highlighting on a button
  1626.             cl3DDkShadow        Windows 95 only: Dark shadow for three-dimensional display elements
  1627.             cl3DLight           Windows 95 only: Light color for three-dimensional display elements (for edges facing the light source)
  1628.             clInfoText          Windows 95 only: Text color for tooltip controls
  1629.             clInfoBk            Windows 95 only: Background color for tooltip controls
  1630.  
  1631.             The second half of the colors listed here are Windows system
  1632.             colors. The color that appears depends on the color scheme users
  1633.             are using for Windows. Users can change these colors using the
  1634.             Control Panel in Program Manager. The actual color that appears
  1635.             will vary from system to system. For example, the color fuchsia
  1636.             may appear more blue on one system than another.
  1637.  
  1638.             For example, to output some blue text in the server window:
  1639.  
  1640.                 TextOut > . clBlue blah blah blah ...
  1641.  
  1642.         (2) Specifying an event colour constant. Event colour constants
  1643.             correspond to the colour of the corresponding event type the user
  1644.             has selected in Client setup/Colours and fonts. This allows scripts
  1645.             that you write to automatically adjust to the colours the user
  1646.             wants. The following event colour constants are available.
  1647.  
  1648.             ecJOIN              Join colour
  1649.             ecPART              Part colour
  1650.             ecQUIT              Quit colour
  1651.             ecTOPIC             Topic change colour
  1652.             ecMODE              Mode change colour
  1653.             ecKICK              Kick colour
  1654.             ecPRIVMSG           Private message colour
  1655.             ecNOTICE            Notice colour
  1656.             ecCTCP              CTCP colour
  1657.             ecACTION            Action colour
  1658.             ecNICK              Nick change colour
  1659.             ecMyChanText        Colour of channel text the user has entered himself
  1660.             ecChanText          Colour of channel text other users have entered
  1661.             ecMyQueryText       Colour of query text the user has entered himself
  1662.             ecQueryText         Colour of query text other users have entered
  1663.             ecServText          Colour of server text
  1664.             ecError             Colour of error text
  1665.             ecScript or ecXDCC  Colour of script (e.g. XDCC) status messages
  1666.  
  1667.             For example:
  1668.  
  1669.                 TextOut ecKICK This text will appear in the same colour as channel kicks do.
  1670.  
  1671.         (3) Specifying a hex RGB value, in the form $bbggrr.
  1672.  
  1673.  
  1674.             For example:
  1675.  
  1676.                 TextOut $0000FF This text is red.
  1677.                 TextOut $00FF00 This text is green.
  1678.                 TextOut $FF0000 This text is blue.
  1679.                 TextOut $00FFFF This text is yellow.
  1680.                 TextOut $FFFFFF This text is white.
  1681.                 TextOut $000000 This text is black.
  1682.  
  1683.         (4) Specifying a decimal RGB value. This is rather useless, unless
  1684.             you're specifying the text colour as a random number, e.g.
  1685.  
  1686.                 TextOut $rand($FFFFFF) This text appears in a random colour.
  1687.  
  1688. New in 0.80, with ObjectViRCScript, you can also specify the handle of a
  1689. TRichEdit object you have created (see OBJECTVS.TXT) to output text to that
  1690. TRichEdit control. However, in order for TextOut to recognize the handle as
  1691. an ObjectViRCScript object handle, it must be preceded with %. Example to
  1692. create a form with a TRichEdit on it and write some text to it (BTW, the
  1693. @p $edit.Align = 5 line simply makes the TRichEdit automatically fill the form,
  1694. so there's no need to specify a size initally by setting the Left, Top etc.
  1695. properties. Align = 5 corresponds to Delphi's Align = alClient. You'll be able
  1696. to specify the properties by textual name shortly, but for now you'll just have
  1697. to fiddle with the numbers until you get the effect you want!!):
  1698.  
  1699. @ $form = $new(TForm)
  1700. @p $form.Left = 20
  1701. @p $form.Top = 20
  1702. @p $form.Width = 300
  1703. @p $form.Height = 300
  1704. @p $form.Visible = 1
  1705.  
  1706. @ $edit = $new(TRichEdit ownedby $form)
  1707. @p $edit.Align = 5
  1708. @p $edit.Visible = 1
  1709.  
  1710. TextOut > %$edit clBlue This text will appear in \bblue\b!!
  1711. TextOut > %$edit clRed This text will appear in \bred\b!!
  1712.  
  1713. [2.4.1.3] TextOutBitmap statement
  1714. ---------------------------------
  1715.  
  1716. Usage: TextOutBitmap [> window] <colour> <bitmap> <text ...>
  1717.  
  1718. Displays some text in a window, along with a small bitmap to the left of the
  1719. text. Otherwise, exactly the same as the TEXTOUT statement described above.
  1720. The bitmap parameter is usually a value returned by the BITMAP function. For
  1721. example:
  1722.  
  1723.         TextOutBitmap > #virc clBlack $bitmap(_join.bmp) Welcome to #virc!
  1724.  
  1725. See the BITMAP function for more information on bitmaps.
  1726.  
  1727. [2.4.2] Flow control commands
  1728. -----------------------------
  1729.  
  1730. [2.4.2.1] Break command
  1731. -----------------------
  1732.  
  1733. Usage: Break [if condition]
  1734.  
  1735. Quits from the currently-executing code block. A code block is something like
  1736. the code between if/endif, while/endwhile, parse/endparse etc. If this
  1737. statement is executed outside a code block, execution of your script routine
  1738. will stop (see the HALT command). If a BREAK statement is encountered inside
  1739. a FOR or WHILE loop, control will immediately be transferred out of the loop.
  1740.  
  1741. If a condition is specified, the break will only occur if the condition is
  1742. met, for example, the following code will print 0, 1, 2, 3 and 4 in the server
  1743. window:
  1744.  
  1745.         for (@l $i = 0; $i <= 10; $i++)
  1746.           Break if ($i == 5)
  1747.           TextOut > . clBlue $i
  1748.         endfor
  1749.  
  1750. [2.4.2.2] Continue command
  1751. --------------------------
  1752.  
  1753. Usage: Continue [if condition]
  1754.  
  1755. Only used within FOR and WHILE blocks, CONTINUE causes the next iteration of
  1756. the loop to begin immediately, without finishing the current iteration.
  1757.  
  1758. If a condition is specified, the continue will only occur if the condition is
  1759. met, for example, the following code will print 0, 1, 2, 3, 4, 6, 7 and 8 in
  1760. the server window:
  1761.  
  1762.         for (@l $i = 0; $i <= 10; $i++)
  1763.           Continue if ($i == 5)
  1764.           TextOut > . clBlue $i
  1765.         endfor
  1766.  
  1767. [2.4.2.4] FallThrough command
  1768. -----------------------------
  1769.  
  1770. Usage: FallThrough
  1771.  
  1772. This powerful command makes event programming much easier. If you've defined a
  1773. special event, but you only want it to execute sometimes, and the rest of the
  1774. time you want the system to behave as if the event was never defined, you can
  1775. use the FallThrough statement to pass the event down to a handler of lower
  1776. priority. A good example is if you're writing, for example, a channel
  1777. statistics script, which catches WHO replies (* 352 *) and processes them,
  1778. without displaying them in the server notices window. However, if the user has
  1779. not typed /chanst, then the regular <default> event should be executed to
  1780. display the WHO on the screen in the normal way. The event would be defined
  1781. like this:
  1782.  
  1783. Event ChanStatWHOReply 5 "* 352 *"
  1784.   if ($doingchanst)
  1785.      ...
  1786.   else
  1787.      FallThrough
  1788.   endif
  1789.  
  1790. [2.4.2.3] Halt command
  1791. ----------------------
  1792.  
  1793. Usage: Halt [if condition]
  1794.  
  1795. Similar to the BREAK command, only exits from ALL code blocks and terminates
  1796. execution of your script. As with BREAK, an optional condition can be
  1797. specified, and the HALT will only occur if the condition is met.
  1798.  
  1799. [2.4.2.5] Yield command
  1800. -----------------------
  1801.  
  1802. Usage: Yield
  1803.  
  1804. Polls the Windows message queue and processes waiting messages. If you're
  1805. writing a script that uses a while loop that takes a long time to execute, it
  1806. may be a good idea to use YIELD to prevent the system from locking up while
  1807. your script is executing. For example, the following will lock V97 up:
  1808.  
  1809.         while (1)
  1810.         endwhile
  1811.  
  1812. However, the following will not lock V97 up, although it'll slow it down a
  1813. little because it is actually executing the while loop over and over again,
  1814. ad infinitum:
  1815.  
  1816.         while (1)
  1817.           Yield
  1818.         endwhile
  1819.  
  1820. The YIELD command is very useful when implementing background processing.
  1821. Adding a YIELD statement to a time-consuming for loop will allow other tasks to
  1822. continue running in the background while the for loop executes.
  1823.  
  1824. IMPORTANT NOTE!! Things can happen while Yield is executing. Even other VS code
  1825. can execute (e.g. if an event occurs during the Yield statement). Therefore,
  1826. you CANNOT assume that variables like $C will retain their value after
  1827. executing Yield, as another VS code section may have changed them. Therefore,
  1828. always save things like $C to your own variables (e.g. $chan) before executing
  1829. Yield if you wish to ensure that the variables don't change from underneath
  1830. your feet.
  1831.  
  1832. [2.4.3] Alias/event/menu control commands
  1833. -----------------------------------------
  1834.  
  1835. [2.4.3.1] DisableEvent command
  1836. ------------------------------
  1837.  
  1838. Usage: DisableEvent event
  1839.  
  1840. Disables event. When an event is disabled, it will never be triggered.
  1841.  
  1842. [2.4.3.2] EnableEvent command
  1843. -----------------------------
  1844.  
  1845. Usage: EnableEvent event
  1846.  
  1847. Enables event. Use after DisableEvent to re-enable the event to allow it to be
  1848. triggered again.
  1849.  
  1850. [2.4.3.3] FireEvent command
  1851. ---------------------------
  1852.  
  1853. Usage: FireEvent event parameters
  1854.  
  1855. Fires event with parameters. This can either be used to pretend that an event
  1856. was fired by ViRC '97, for example:
  1857.  
  1858.         FireEvent <OnConnect>
  1859.  
  1860. Or, you can define your own custom events, for example <OnOpNick>, which you
  1861. could then fire manually, say, in your MODE event:
  1862.  
  1863.         FireEvent <OnOpNick> $C $nick
  1864.  
  1865. If no parameters are specified, the event is fired unconditionally. If
  1866. parameters are specified, the event is only fired if the event's mask matches
  1867. the parameters specified. You may fire a range of events by including a
  1868. wildcard, for example:
  1869.  
  1870.         FireEvent <OnConnect*
  1871.  
  1872. This would fire all events whose names begin with the string <OnConnect.
  1873.  
  1874. [2.4.3.4] SetAlias command
  1875. --------------------------
  1876.  
  1877. Usage: SetAlias alias = text
  1878.  
  1879. This is a very powerful command which you will use very seldomly, if at all.
  1880. It creates an alias with the ViRCScript code set to text. You can separate
  1881. multiple lines of code in text with $char(13). Examples:
  1882.  
  1883.         @l $code = TextOut > . clBlue Line 1$char(13)
  1884.         @l $code = $codeTextOut > . clBlue Line 2
  1885.  
  1886.         SetAlias TEST1 = $code
  1887.  
  1888. Together with the GETALIAS function, SETALIAS can be used to append ViRCScript
  1889. code to existing aliases. For an example of this usage, see the GETALIAS
  1890. function.
  1891.  
  1892. [2.4.3.5] UnAlias command
  1893. -------------------------
  1894.  
  1895. Usage: UnAlias alias [alias ...]
  1896.  
  1897. Removes one or more aliases. For example, this removes the 3 aliases OP, DEOP
  1898. and J.
  1899.  
  1900.         UnAlias OP DEOP J
  1901.  
  1902. [2.4.3.6] UnEvent command
  1903. -------------------------
  1904.  
  1905. Usage: UnEvent event [event ...]
  1906.  
  1907. Removes one or more events. For example, this removes the 2 events JOIN and
  1908. PART:
  1909.  
  1910.         UnEvent JOIN PART
  1911.  
  1912. [2.4.3.7] UpdateMenus command
  1913. -----------------------------
  1914.  
  1915. Usage: updatemenus
  1916.  
  1917. Recreates all menus and popups from the in-memory menu trees and writes the
  1918. trees to the registry. After you have changed menu(s) with MenuTree and
  1919. MenuItem statements, you must use this command for your changes to take effect
  1920. properly. Failure to execute this command when you've finished altering the
  1921. menus can cause unwanted side-effects, as the in-memory menu trees and the
  1922. actual menus and popups become desynchronized from each other.
  1923.  
  1924. [2.4.4] Window manipulation commands
  1925. ------------------------------------
  1926.  
  1927. [2.4.4.1] Close command
  1928. -----------------------
  1929.  
  1930. Usage: Close window
  1931.  
  1932. Closes window. window can be . to set the focus to the server notices window,
  1933. a channel name, or a nick (query window).
  1934.  
  1935. [2.4.4.2] Max command
  1936. ---------------------
  1937.  
  1938. Usage: Max window
  1939.  
  1940. Maximizes window. window can be . to set the focus to the server notices
  1941. window, a channel name, or a nick (query window).
  1942.  
  1943. [2.4.4.3] Min command
  1944. ---------------------
  1945.  
  1946. Usage: Min window
  1947.  
  1948. Minimizes window. window can be . to set the focus to the server notices
  1949. window, a channel name, or a nick (query window).
  1950.  
  1951. [2.4.4.4] Restore command
  1952. -------------------------
  1953.  
  1954. Usage: Restore window
  1955.  
  1956. Restores window. window can be . to set the focus to the server notices window,
  1957. a channel name, or a nick (query window).
  1958.  
  1959. [2.4.4.5] SetFocus command
  1960. --------------------------
  1961.  
  1962. Usage: SetFocus window
  1963.  
  1964. Sets focus to window. window can be . to set the focus to the server notices
  1965. window, a channel name, or a nick (query window).
  1966.  
  1967. [2.4.5] File I/O commands
  1968. -------------------------
  1969.  
  1970. [2.4.5.2] AppendText command
  1971. ----------------------------
  1972.  
  1973. Usage: AppendText "filename" text
  1974.  
  1975. Appends text to the end of filename. In V96 0.80 and above, filename will be
  1976. created if it doesn't already exist. Putting quotes around filename enables
  1977. filenames and paths containing spaces to work correctly.
  1978.  
  1979. [2.4.5.1] CreateFile command
  1980. ----------------------------
  1981.  
  1982. Usage: CreateFile filename
  1983.  
  1984. Creates filename, or truncates it to 0 bytes if it already exists.
  1985.  
  1986. [2.4.5.5] ChDir command
  1987. -----------------------
  1988.  
  1989. Usage: ChDir dir
  1990.  
  1991. Changes to the dir directory.
  1992.  
  1993. [2.4.5.4] MkDir command
  1994. -----------------------
  1995.  
  1996. Usage: MkDir dir
  1997.  
  1998. Makes a directory called dir.
  1999.  
  2000. [2.4.5.6] RmDir command
  2001. -----------------------
  2002.  
  2003. Usage: RmDir dir
  2004.  
  2005. Removes the dir directory.
  2006.  
  2007. [2.4.5.3] RmFile command
  2008. ------------------------
  2009.  
  2010. Usage: RmFile file
  2011.  
  2012. Erases file.
  2013.  
  2014. [2.4.6] Registry I/O commands
  2015. -----------------------------
  2016.  
  2017. [2.4.6.1] RehashRegistry command
  2018. --------------------------------
  2019.  
  2020. Usage: RehashRegistry
  2021.  
  2022. Makes V97 reload all its settings from the registry. If you're writing a
  2023. program which modifies any of the in-registry settings while V97 is running,
  2024. the program should send a RehashRegistry command to V97 via DDE (see
  2025. VIRCDDE.TXT) to make V97 reload everything from the registry.
  2026.  
  2027. [2.4.6.2] WriteRegistry command
  2028. -------------------------------
  2029.  
  2030. Usage: WriteRegistry "section" key value
  2031.  
  2032. Assigns value to key in the registry under the section "section", located under
  2033. the ViRC '97 key (e.g. having a section of "YyzScript" would write to
  2034. HKEY_CURRENT_USER\Software\MeGALiTH Software\Visual IRC 96\YyzScript. If key
  2035. doesn't exist, it will be created. If key already contains a value, it will
  2036. be overwritten by the new value you're setting. You cannot write outside the
  2037. ViRC '97 key in the registry. This is a conscious design decision to ensure
  2038. maximum security (a buggy or malicious script could go around trashing
  2039. system-required registry entries otherwise).
  2040.  
  2041. [2.4.7] Sound and multimedia commands
  2042. -------------------------------------
  2043.  
  2044. [2.4.7.1] Beep command
  2045. ----------------------
  2046.  
  2047. Usage: Beep
  2048.  
  2049. The name says it all. ;) Produces a standard Windows beep.
  2050.  
  2051. [2.4.7.2] MCI command
  2052. ---------------------
  2053.  
  2054. Usage: MCI command
  2055.  
  2056. Sends command to the Windows MCI (Media Control Interface) system. MCI commands
  2057. can be used to play, stop, and record audio (and more too), and the full syntax
  2058. is beyond the scope of this document and into the realm of the Win32 API help
  2059. file. However, here are some examples to get you started:
  2060.  
  2061.         // Play filename.wav
  2062.         MCI Play filename.wav
  2063.  
  2064.         // Play bach.mid
  2065.         MCI Play bach.mid
  2066.  
  2067.         // Stop playing bach.mid
  2068.         MCI Stop bach.mid
  2069.  
  2070.         // Start recording audio to test.wav
  2071.         MCI Record test.wav
  2072.  
  2073.         // Stop recording audio to test.wav
  2074.         MCI Stop test.wav
  2075.  
  2076. [2.4.8] Server (and IRC) commands
  2077. ---------------------------------
  2078.  
  2079. [2.4.8.1] Say command
  2080. ---------------------
  2081.  
  2082. Usage: Say channel text
  2083.  
  2084. Sends the message text to channel. Use in scripts to send text to a channel. I
  2085. believe this has been undocumented since around 0.30. =]
  2086.  
  2087. [2.4.8.2] ASay command
  2088. ----------------------
  2089.  
  2090. Usage: ASay text
  2091.  
  2092. Says text to every channel you are currently on.
  2093.  
  2094. [2.4.8.3] AMe command
  2095. ---------------------
  2096.  
  2097. Usage: AMe text
  2098.  
  2099. Executes /me text to every channel you are currently on.
  2100.  
  2101. [2.4.8.4] SimulateServerData command
  2102. ------------------------------------
  2103.  
  2104. Usage: SimulateServerData text
  2105.  
  2106. Puts text directly into ViRC '97's received data buffer, making V97 behave as
  2107. if text was received from the server. This is very useful as it allows you to
  2108. test new events you've written offline, and, possibly more usefully, to simply
  2109. make DCC connections to a certain IP address and port from a script. In clients
  2110. like mIRC which don't have this function, you have to send a CTCP to yourself,
  2111. but this isn't a good idea as you have to wait for the request to come back,
  2112. which is subject to server lag, and won't work if you're not connected to an
  2113. IRC server. This command can get around that. For example:
  2114.  
  2115.         SimulateServerData :test!virc@megalith.co.uk PRIVMSG blah :This is a test!!
  2116.  
  2117. This would make it appear exactly as if you received a private message from
  2118. a user whose nick is test and whose email address is virc@megalith.co.uk. There
  2119. is no way to differentiate between real and simulated server events in your
  2120. scripts.
  2121.  
  2122. [2.4.8.5] Using regular IRC commands
  2123. ------------------------------------
  2124.  
  2125. Usage: [^][*]command ...
  2126.  
  2127. Regular IRC commands may be used in VS (of course ;), only the slash prefix is
  2128. optional and should be left out, and the code looks neater without it. In
  2129. addition, the command can be prefixed with ^, * or ^*.
  2130.  
  2131. A prefix of ^ surpresses the output of any text that the command directly
  2132. causes. For example, V97 contains code in its built-in MSG command to display
  2133. the message you're sending on the screen. ^MSG will send the message, but
  2134. surpress the text output.
  2135.  
  2136. A prefix of * passes the command straight into V97's built-in command
  2137. interpreter, without executing any aliases. This is very useful if you're
  2138. trying to override built-in commands, as, for example, if you want to call
  2139. V97's MSG command in your new MSG alias, you need to call the command as *MSG
  2140. to avoid the alias calling itself recursively.
  2141.  
  2142. Both prefixes can be combined as ^*. Please note that a prefix of *^ is
  2143. INVALID, and will not work.
  2144.  
  2145. The following code will change the text displayed when the user uses the /msg
  2146. command to something a little more fancy, demonstrating how to override a
  2147. built-in command:
  2148.  
  2149. Alias MSG
  2150.   TextOut ecPRIVMSG [*>\b$1\b<*]\t$2-
  2151.   ^*Msg $1-
  2152. EndAlias
  2153.  
  2154. [2.4.9] Inter-server communication commands
  2155. -------------------------------------------
  2156.  
  2157. [2.4.9.1] OnServer
  2158. ------------------
  2159.  
  2160. Usage: OnServer index command
  2161.  
  2162. Executes command on the IRC server connection index. The best way to explain
  2163. how to use this function is to use a simple example, which will also make use
  2164. of the $ServerList() function.
  2165.  
  2166. 7ay, for example, you're on 2 IRC servers: irc.ionet.net:6667 and
  2167. efnet.demon.co.uk:6666. The server connection that the script is running under
  2168. is irc.ionet.net:6667 (for example, if the user typed an alias from the
  2169. irc.ionet.net:6667 server window or any of its channel, query or DCC windows),
  2170. but you want to execute a command on the other server, efnet.demon.co.uk:6666.
  2171. First, you'd get the list of server connections with the $ServerList()
  2172. function, which would return:
  2173.  
  2174.         irc.ionet.net:6667 efnet.demon.co.uk:6666
  2175.  
  2176. (Note that the first server in the list (list index 0) is not necessarily the
  2177. active server connection - use the $CurrentServer() function to retrieve the
  2178. index of the current server.)
  2179.  
  2180. With this, your script could find out what the active server connection is.
  2181. $CurrentServer() would return:
  2182.  
  2183.         0
  2184.  
  2185. Hence, the script could, if necessary, display the name of the active server
  2186. connection with this code:
  2187.  
  2188.         TextOut > . clBlack *** The active server connection is: $listIndex($CurrentServer() $ServerList())
  2189.  
  2190. Now that the active server is known to be number 0, and hence the other server
  2191. is number 1, the script could execute an IRC command on the other server as
  2192. follows:
  2193.  
  2194.         OnServer 1 Join #virc
  2195.  
  2196. Note that only that command is executed on the IRC server number 1. All
  2197. subsequent IRC commands are executed on the server that was previously active.
  2198.  
  2199. [2.4.10] Miscellaneous commands
  2200. -------------------------------
  2201.  
  2202. [2.4.10.1] AcceptDCC command
  2203. ----------------------------
  2204.  
  2205. Usage: AcceptDCC
  2206.        AcceptDCC filename
  2207.  
  2208. When called inside an <OnAcceptDCCQuery> event, accepts the incoming DCC
  2209. connection without any confirmation from the user, regardless of the DCC
  2210. settings specified in Client setup.
  2211.  
  2212. If a filename is specified, then the incoming file will be saved under that
  2213. filename (as if the user had manually chosen to rename the incoming file).
  2214.  
  2215. [2.4.10.2] AddToIAL command
  2216. ---------------------------
  2217.  
  2218. Usage: AddToIAL channel nick user@host
  2219.  
  2220. Adds nick, with email address user@host, to channel's IAL (Internal Address
  2221. List). The IAL is used as a cache for the GetAddress function, so the server
  2222. does not have to be queried each time the function is used, speeding this
  2223. valuable function up and pretty much eliminating server lag. When a user joins
  2224. a channel, speaks in a channel, or makes a mode change in a channel, the user
  2225. is added to the channel's IAL automatically, and is removed when that user
  2226. leaves the channel or quits IRC. The whole of the channel's IAL is cleared when
  2227. you leave that channel. Use AddToIAL to force an entry into the IAL which V97
  2228. would not add on its own. For example, if you want to cache all the WHO replies
  2229. on a channel in the IAL, you can write an event handler which parses each WHO
  2230. reply and adds each entry manually. ViRC '97 will then "take care" of those
  2231. manually-added entries itself, deleting them when necessary and so forth.
  2232.  
  2233. For more information on the IAL, see the GetAddress function.
  2234.  
  2235. [2.4.10.3] CancelDCC command
  2236. ----------------------------
  2237.  
  2238. Usage: CancelDCC
  2239.  
  2240. When called inside an <OnAcceptDCCQuery> event, cancels the incoming DCC
  2241. connection without any confirmation from the user, regardless of the DCC
  2242. settings specified in Client setup.
  2243.  
  2244. [2.4.10.4] DDE command
  2245. ----------------------
  2246.  
  2247. Usage: DDE service topic "item" text
  2248.  
  2249. Syntactically identical to mIRC's command of the same name. Connects to a DDE
  2250. server using the details supplied and sends text by DDE. This command can also
  2251. be used as a function, i.e. $dde(service topic "item" text), and will return
  2252. any data received from the DDE server as a result of the DDE function.
  2253.  
  2254. [2.4.10.5] DisableInternalXDCCEvents
  2255. ------------------------------------
  2256.  
  2257. Usage: DisableInternalXDCCEvents
  2258.  
  2259. Disables all internal XDCC processing. V97 will no longer respond to XDCC
  2260. requests from other users, and the standard events will be called when an
  2261. XDCC request is received, just as if it were a standard PRIVMSG or CTCP. Use
  2262. this if you wish to override the built-in XDCC mechanism in your own script.
  2263.  
  2264. [2.4.10.6] DNS command
  2265. ----------------------
  2266.  
  2267. Usage: DNS host
  2268.  
  2269. The DNS command will take a hostname as a parameter and display on the screen
  2270. the corresponding IP address. Example:
  2271.  
  2272.         DNS jimc.demon.co.uk
  2273.  
  2274. Will display:
  2275.  
  2276.         *** DNS lookup: jimc.demon.co.uk resolves to 158.152.45.81
  2277.  
  2278. [2.4.10.7] EnableInternalXDCCEvents
  2279. -----------------------------------
  2280.  
  2281. Usage: EnableInternalXDCCEvents
  2282.  
  2283. Re-enables all internal XDCC processing after DisableIncomingXDCCEvents has
  2284. been called. V97 will then respond to XDCC requests from other users. Use
  2285. this if you wish to re-enable V97's internal XDCC mechanism after you have
  2286. overriden it in your own script.
  2287.  
  2288. [2.4.10.8] Eval command
  2289. -----------------------
  2290.  
  2291. Usage: Eval command
  2292.        $eval(text)
  2293.  
  2294. Normally, commands are evaluated before executing them. Placing EVAL before a
  2295. command line causes the line to be evaluated twice before executing. You'd
  2296. probably never have to use this in your scripts, except when evaluating
  2297. expressions that are stored somewhere else, for example, a line in a file.
  2298. To get a random line from a file, evaluate that line, and store in $x, you'd
  2299. use:
  2300.  
  2301.         Eval @ $$x = $randomread(filename.txt)
  2302.  
  2303. EVAL can also be called as a function, in which case text is evaluated, and
  2304. the evaluated text is returned, rather than being executed, as with the EVAL
  2305. command. Hence, the above line could be rewritten as:
  2306.  
  2307.         @ $x = $eval($randomread(filename.txt))
  2308.  
  2309. [2.4.10.9] Name command
  2310. -----------------------
  2311.  
  2312. Usage: Name text
  2313.  
  2314. Names your script text. This isn't really a command at all. It's used by the
  2315. script loader to display your script's name in the loading progress dialog box.
  2316. It's recommended you use NAME to give your script a sensible name at the top of
  2317. the file, so people know what they're loading.
  2318.  
  2319. [2.4.10.10] NoAttribs command
  2320. -----------------------------
  2321.  
  2322. Usage: NoAttribs command
  2323.  
  2324. Executes command as normal, but surpresses attribute (\b, \u, \i and \t)
  2325. parsing. For example, the following statement will not work as desired (try
  2326. it):
  2327.  
  2328.         Say #channel I'll send you the file c:\unix\tftp.
  2329.  
  2330. This is because V97's parser will pick up the \u and \t in your "filename" and
  2331. will translate them to the underline and tab formatting codes. The solution is
  2332. to prefix the command with NoAttribs, which surpresses parsing of formatting
  2333. codes:
  2334.  
  2335.         NoAttribs Say #channel I'll send you the file c:\unix\tftp.
  2336.  
  2337. This will work as desired (try this too if you don't understand this fully).
  2338.  
  2339. [2.4.10.11] MessageBox command
  2340. ------------------------------
  2341.  
  2342. Usage: MessageBox text
  2343.  
  2344. Displays a message box on the screen with an OK button, with text as its
  2345. contents. Use this in scripts to inform the user of something.
  2346.  
  2347. [2.4.10.12] SetInputLine command
  2348. --------------------------------
  2349.  
  2350. Usage: SetInputLine window text
  2351.  
  2352. Sets the the contents of window's command entry box to text. window can be .
  2353. (a period) for the server notices window, a channel name for a channel window,
  2354. a nick for a query window, or =nick for a DCC Chat window.
  2355.  
  2356. [2.4.10.13] UserAdd command
  2357. ---------------------------
  2358.  
  2359. Usage: UserAdd mask userlevel banlevel protlevel
  2360.        UserAdd mask userlevel banlevel protlevel customlevel
  2361.  
  2362. Adds mask (in nick!user@host form), which may contain wildcards, to the
  2363. userlist, assigning it the specified userlevel, banlevel and protlevel.
  2364. The levels assigned may be between 0 and 1048576 (1M), and have no real
  2365. built-in meaning (although a few userlevels are used in DEFAULT.LIB), so you
  2366. can assign whatever meaning you want to each level in your script. Specifying
  2367. a level of -1 leaves mask's current level unchanged (or sets the level to 0 if
  2368. mask isn't already in the userlist). Example:
  2369.  
  2370.         UserAdd *!*megalith@*demon.co.uk 1 0 0
  2371.         // The above adds the mask *!*megalith@*demon.co.uk to the userlist
  2372.         // with a userlevel of 1, a banlevel of 0 and a protlevel of 0.
  2373.  
  2374.         UserAdd *!*megalith@*demon.co.uk 10 -1 -1
  2375.         // The above increases *!*megalith@*demon.co.uk's userlevel to 10,
  2376.         // leaving the banlevel and protlevel unchanged.
  2377.  
  2378. The userlevel, banlevel and protlevel of a mask can be retrieved with the
  2379. GETUSERLEVEL, GETBANLEVEL and GETPROTLEVEL functions respectively.
  2380.  
  2381. Additionally, a customlevel may be specified. The customlevel can be any text
  2382. string to assign to the mask - it doesn't have to be a number. No internal
  2383. meaning is assigned to the customlevel, nor is it used by DEFAULT.LIB, so if
  2384. you're designing your own userlevel system and wish to store any additional
  2385. information or flags for the user, store them in the customlevel. If no
  2386. customlevel is supplied on the command line, the customlevel is unchanged.
  2387. Example:
  2388.  
  2389.         UserAdd *!*megalith@*demon.co.uk -1 -1 -1 This is a test.
  2390.         // The above doesn't change the userlevel, banlevel or protlevel of
  2391.         // *!*megalith@*demon.co.uk, but changes the customlevel to the string
  2392.         // "This is a test.".
  2393.  
  2394.         UserAdd *!*megalith@*demon.co.uk 0 20 -1
  2395.         // The above changes *!*megalith@*demon.co.uk's userlevel to 0 and
  2396.         // banlevel to 20, leaving the protlevel and the customlevel unchanged.
  2397.  
  2398. The customlevel of a mask can be retrieved with the GETCUSTOMLEVEL function.
  2399.  
  2400. [2.4.10.14] UserDelete command
  2401. ------------------------------
  2402.  
  2403. Usage: UserDelete mask
  2404.  
  2405. Deletes the single, specific entry mask (in nick!user@host form), which may
  2406. contain wildcards, from the userlist. For example, if the userlist contains:
  2407.  
  2408.         *!*@*.com
  2409.         user1!*@*.com
  2410.         user2!*@*.com
  2411.  
  2412. This command will only delete the first entry, *!*@*.com, not the others,
  2413. because wildcard comparison between the mask specified as the parameter and
  2414. each mask in the userlist is NOT performed:
  2415.  
  2416.         UserDelete *!*@*.com
  2417.  
  2418. [2.4.10.15] UserDeleteWithWildcards command
  2419. -------------------------------------------
  2420.  
  2421. Usage: UserDeleteWithWildcards mask
  2422.  
  2423. Deletes any entry from the userlist whose mask matches the mask (in
  2424. nick!user@host form), which may contain wildcards, specified as the parameter.
  2425. For example, if the userlist contains:
  2426.  
  2427.         *!*@*.com
  2428.         user1!*@*.com
  2429.         user2!*@*.com
  2430.  
  2431. This command will delete every entry from the userlist, because wildcard
  2432. comparison between the mask specified as the parameter and each mask in the
  2433. userlist IS performed:
  2434.  
  2435.         UserDeleteWithWildcards *!*@*.com
  2436.  
  2437. [2.4.11] Debugging commands
  2438. ---------------------------
  2439.  
  2440. [2.4.11.1] EvaluateWindow command
  2441. ---------------------------------
  2442.  
  2443. Usage: EvaluateWindow
  2444.  
  2445. Pops up a window, similar to Delphi's variable evaluation window, which allows
  2446. expressions to be evaluated at run-time. You can, for example, place an
  2447. EvaluateWindow command stategically in your code for debugging to examine the
  2448. contents of variables at a particular point.
  2449.  
  2450. [2.5] Functions
  2451. ---------------
  2452.  
  2453. [2.5.1] String manipulation functions
  2454. -------------------------------------
  2455.  
  2456. [2.5.1.1] Asc function
  2457. ----------------------
  2458.  
  2459. Usage: $asc(char)
  2460.  
  2461. Returns the ASCII value for char. For example, $asc(A) = 65, as the ASCII code
  2462. for the character A is 65.
  2463.  
  2464. [2.5.1.2] Char function
  2465. -----------------------
  2466.  
  2467. Usage: $char(value)
  2468.  
  2469. Returns the character for value. For example, $asc(65) = A, as the character
  2470. A corresponds to the ASCII code 65.
  2471.  
  2472. [2.5.1.3] IsNumeric function
  2473. ----------------------------
  2474.  
  2475. Usage: $isnumeric(num)
  2476.  
  2477. Returns 1 if num is a number, and 0 if num is not a number. Examples:
  2478.  
  2479.         $isnumeric(1234) = 1
  2480.         $isnumeric(hello) = 0
  2481.  
  2482. [2.5.1.4] IsChannel function
  2483. ----------------------------
  2484.  
  2485. Usage: $ischannel(channel)
  2486.  
  2487. Returns 1 if channel is a valid channel name, otherwise returns 0. Examples:
  2488.  
  2489.         $ischannel(#quake) = 1
  2490.         $ischannel(&local) = 1
  2491.         $ischannel(xyz) = 0
  2492.  
  2493. [2.5.1.5] IsURL function
  2494. ------------------------
  2495.  
  2496. Usage: $isurl(url)
  2497.  
  2498. Returns 1 if url is a valid URL (an address that a web browser can handle).
  2499. Examples:
  2500.  
  2501.         $isurl(http://www.megalith.co.uk) = 1
  2502.         $isurl(mailto:acable@sv.span.com) = 1
  2503.         $isurl(www.microsoft.com) = 1
  2504.         $isurl(ftp.htsoft.com) = 1
  2505.         $isurl(blah.xyz.com) = 0
  2506.  
  2507. [2.5.1.6] Length function
  2508. -------------------------
  2509.  
  2510. Usage: $length(text)
  2511.  
  2512. Returns the length of text in characters. Example:
  2513.  
  2514.         $length(hello) = 5
  2515.  
  2516. [2.5.1.7] Lower function
  2517. ------------------------
  2518.  
  2519. Usage: $lower(text)
  2520.  
  2521. Converts the given text to lower case. For example:
  2522.  
  2523.         $lower(BLAH) = blah
  2524.  
  2525. [2.5.1.8] MaskMatch function
  2526. ----------------------------
  2527.  
  2528. Usage: $maskmatch(text mask)
  2529.  
  2530. Matches text against mask. Use MASKMATCH, and _not_ WILDMATCH, if you're trying
  2531. to match a nick!user@host-style mask. Example:
  2532.  
  2533.         $maskmatch(MeGALiTH!~megalith@jimc.demon.co.uk *!*megalith@*demon.co.uk) = 1
  2534.  
  2535. Mask comparisons are case-insensitive.
  2536.  
  2537. [2.5.1.9] RStrPos function
  2538. --------------------------
  2539.  
  2540. Usage: $rstrpos(needle haystack)
  2541.  
  2542. The reverse of STRPOS. Finds the last occurrence of needle within haystack, and
  2543. returns the character position of needle. 0 is returned if needle is not found
  2544. in haystack. For example:
  2545.  
  2546.         $rstrpos(x abxcdxba) = 6
  2547.         $rstrpos(dx abxcdxba) = 5
  2548.         $rstrpos(blah hahahahha) = 0
  2549.  
  2550. [2.5.1.10] RStrTokL function
  2551. ----------------------------
  2552.  
  2553. Usage: $rstrtokl(token text)
  2554.  
  2555. The reverse of STRTOKL. Searches for token within text, and returns everything
  2556. to the left of the last occurrence of token. If token can't be found, returns
  2557. text unchanged.
  2558.  
  2559.         $rstrtokl(. www.megalith.co.uk) = www.megalith.co
  2560.         $rstrtokl(q abc123xyz) = abc123xyz
  2561.  
  2562. [2.5.1.11] RStrTokR function
  2563. ----------------------------
  2564.  
  2565. Usage: $rstrtokr(token text)
  2566.  
  2567. The reverse of STRTOKR. Searches for token within text, and returns everything
  2568. to the right of the last occurrence of token. If token can't be found, returns
  2569. an empty string.
  2570.  
  2571.         $rstrtokr(. www.megalith.co.uk) = uk
  2572.         $rstrtokr(q abc123xyz) =
  2573.  
  2574. [2.5.1.12] StrPos function
  2575. --------------------------
  2576.  
  2577. Usage: $strpos(needle haystack)
  2578.  
  2579. Finds the first occurrence of needle within haystack, and returns the character
  2580. position of needle. 0 is returned if needle is not found in haystack. For
  2581. example:
  2582.  
  2583.         $strpos(cd abcdefg) = 3
  2584.         $strpos(blah hahahahha) = 0
  2585.  
  2586. [2.5.1.13] StrPosFrom function
  2587. ------------------------------
  2588.  
  2589. Usage: $strposfrom(position needle haystack)
  2590.  
  2591. Starting from the character at position (where 1 is the first character in the
  2592. string) and onwards, finds needle within haystack, and returns the character
  2593. position of needle. 0 is returned if needle is not found in haystack. For
  2594. example:
  2595.  
  2596.         $strposfrom(5 cd abcdefcdg) = 7
  2597.         $strposfrom(4 blah hahahahha) = 0
  2598.  
  2599. [2.5.1.14] StrTokL function
  2600. ---------------------------
  2601.  
  2602. Usage: $strtokl(token text)
  2603.  
  2604. Searches for token within text, and returns everything to the left of the first
  2605. occurrence of token. If token can't be found, returns text unchanged.
  2606.  
  2607.         $strtokl(. www.megalith.co.uk) = www
  2608.         $strtokl(q abc123xyz) = abc123xyz
  2609.  
  2610. [2.5.1.15] StrTokR function
  2611. ---------------------------
  2612.  
  2613. Usage: $strtokr(token text)
  2614.  
  2615. Searches for token within text, and returns everything to the right of the
  2616. first occurrence of token. If token can't be found, returns an empty string.
  2617.  
  2618.         $strtokr(. www.megalith.co.uk) = megalith.co.uk
  2619.         $strtokr(q abc123xyz) =
  2620.  
  2621. [2.5.1.16] StrTrim function
  2622. ---------------------------
  2623.  
  2624. Usage: $strtrim(text)
  2625.  
  2626. Removes control characters and the preceding colon, if present, from text. This
  2627. is very useful, as many lines received from the IRC server contain parameters
  2628. prefixed by a colon.
  2629.  
  2630. Example: Consider this line of server text.
  2631.  
  2632.         :nick!user@host PRIVMSG #channel :well, what's up everybody!!
  2633.  
  2634. To extract the actual message sent to the channel correctly, you would use
  2635. $strtrim($3-). This function will also remove the \A character from the
  2636. beginning of CTCPs.
  2637.  
  2638. [2.5.1.17] SubStr function
  2639. --------------------------
  2640.  
  2641. Usage: $substr(text start num)
  2642.  
  2643. Returns num characters at start from text. Exactly equivalent to Delphi's
  2644. Copy(text, start, num) function or VB's Mid$(text, start, num) function.
  2645. Example:
  2646.  
  2647.         $substr(abcdef 2 3) = bcd
  2648.  
  2649. [2.5.1.18] Upper function
  2650. -------------------------
  2651.  
  2652. Usage: $upper(text)
  2653.  
  2654. Converts the given text to upper case. For example:
  2655.  
  2656.         $upper(blah) = BLAH
  2657.  
  2658. [2.5.1.19] WildMatch function
  2659. -----------------------------
  2660.  
  2661. Usage: $wildmatch(text mask)
  2662.  
  2663. Matches text against mask, which can contain wildcards. Examples:
  2664.  
  2665.         $wildmatch(blah *lah) = 1
  2666.         $wildmatch(blah bla*) = 1
  2667.         $wildmatch(blah *la*) = 1
  2668.         $wildmatch(blah *) = 1
  2669.         $wildmatch(blah *hah) = 0
  2670.  
  2671. Mask comparisons are case-insensitive. text may contain spaces. mask, however,
  2672. may not.
  2673.  
  2674. [2.5.1.20] WordCount function
  2675. -----------------------------
  2676.  
  2677. Usage: $wordcount(text)
  2678.  
  2679. *** NOTE: This function has been superceded by the listElementCount function,
  2680. although the WordCount function is still available for backwards compatibility
  2681. with old scripts.
  2682.  
  2683. Returns the number of words in text. Examples:
  2684.  
  2685.         $wordcount()            = 0
  2686.         $wordcount(abc)         = 1
  2687.         $wordcount(a b c)       = 3
  2688.  
  2689. This is very useful if you wish to find out the number of parameters passed to
  2690. an alias, for example. You would use something like:
  2691.  
  2692.         @l $paramcount = $wordcount($1-)
  2693.  
  2694. [2.5.2] List manipulation functions
  2695. -----------------------------------
  2696.  
  2697. V97 0.94pre7 and above support lists, a feature very similar to the lists in
  2698. TCL. Basically, whereas the regular string manipulation functions in VS work
  2699. on characters (e.g. SUBSTR returns a range of characters, STRPOS searches for
  2700. one or more characters within the string), the list functions work on words,
  2701. which, to use the correct terminology, are called elements. The first element
  2702. in a list has index 0. Elements in a list are separated by spaces. If you want
  2703. to have an element in a list which actually contains a space itself, you must
  2704. enclose the whole element in quotation marks ("). As lists are just strings,
  2705. they are defined as normal variables, just like anything else. Here are some
  2706. examples:
  2707.  
  2708.         // A list with four elements
  2709.         @ $x = zero one two three
  2710.         // This will display: two
  2711.         MessageBox $listIndex(2 $x)
  2712.  
  2713.         // A list with elements containing spaces
  2714.         @ $x = Jack "John Smith" Jill "Chris Jones"
  2715.         // This will display: Chris Jones
  2716.         MessageBox $listIndex(3 $x)
  2717.  
  2718. Lists are an extremely powerful feature. Get to know the different functions
  2719. available well. Development of many complex scripts can be made dramatically
  2720. simpler by good use of lists.
  2721.  
  2722. Note that, with all the below functions, if you wish to specify one element
  2723. that contains a space, enclose it with quotes (").
  2724.  
  2725. [2.5.2.1] listElementCount function
  2726. -----------------------------------
  2727.  
  2728. Usage: $listElementCount(list)
  2729.  
  2730. Returns the number of elements in list. Examples:
  2731.  
  2732.         @ $x = zero one two three
  2733.         // This will display: 4
  2734.         MessageBox $listElementCount($x)
  2735.  
  2736.         @ $x = "one two" "three four" five six "seven eight"
  2737.         // This will display: 5
  2738.         MessageBox $listElementCount($x)
  2739.  
  2740. In case the second example isn't clear, that list contains 5 elements, which
  2741. are: "one two", "three four", five, six, and "seven eight".
  2742.  
  2743. [2.5.2.2] listIndex function
  2744. ----------------------------
  2745.  
  2746. Usage: $listIndex(index list)
  2747.  
  2748. Returns element index from list. The first element in the list is at index 0.
  2749. Examples:
  2750.  
  2751.         @ $x = zero one two three four
  2752.         // This will display: one
  2753.         MessageBox $listIndex(1 $x)
  2754.  
  2755.         // This will display: three
  2756.         MessageBox $listIndex(3 $x)
  2757.  
  2758. [2.5.2.3] listIndexOf function
  2759. ------------------------------
  2760.  
  2761. Usage: $listIndexOf(element list)
  2762.  
  2763. Returns the index of element in list. The first element in the list is at index
  2764. 0, the second is at index 1, and so forth. If element isn't present in list,
  2765. this function will return -1. element can contain wildcard characters.
  2766.  
  2767. Examples:
  2768.  
  2769.         @ $x = zero one two three four
  2770.         // This will display: 3
  2771.         MessageBox $listIndexOf(three $x)
  2772.  
  2773.         // This will display: 2
  2774.         MessageBox $listIndexOf(*w* $x)
  2775.  
  2776.         // This will display: -1
  2777.         MessageBox $listIndexOf(five $x)
  2778.  
  2779. [2.5.2.4] listInsert function
  2780. -----------------------------
  2781.  
  2782. Usage: $listInsert(index element list)
  2783.  
  2784. Inserts element at position index into list. Example:
  2785.  
  2786.         @ $x = 0 1 2 3 4 5
  2787.         // This will display: 0 1 2 X 3 4 5
  2788.         MessageBox $listInsert(3 X $x)
  2789.  
  2790. [2.5.2.5] listJoin function
  2791. ---------------------------
  2792.  
  2793. Usage: $listJoin(delimiter list)
  2794.  
  2795. Returns list, with each element separated by delimeter. Examples:
  2796.  
  2797.         @ $x = Jack Jill Bill Ben
  2798.         // This will display: Jack,Jill,Bill,Ben
  2799.         MessageBox $listJoin(, $x)
  2800.  
  2801.         // This will display: Jack and Jill and Bill and Ben
  2802.         MessageBox $listJoin (" and " $x)
  2803.  
  2804. [2.5.2.6] listRange function
  2805. ----------------------------
  2806.  
  2807. Usage: $listRange(start end list)
  2808.  
  2809. Returns one or more elements from list, starting from start and ending at end.
  2810. Example:
  2811.  
  2812.         @ $x = zero one two three four
  2813.         // This will display: one two three
  2814.         MessageBox $listRange(1 3 $x)
  2815.  
  2816. [2.5.2.7] listRemove function
  2817. -----------------------------
  2818.  
  2819. Usage: $listRemove(mask list)
  2820.  
  2821. Returns another list which contains every element in list that is not matched
  2822. by mask. Effectively removes one or more items from the list. Examples:
  2823.  
  2824.         @ $x = one two ten twenty-two
  2825.         // This will return a list with the element "two" removed. This will
  2826.         // display: one ten twenty-two
  2827.         MessageBox $listRemove(two $x)
  2828.  
  2829.         // This will return a list with any items matching the mask *two*
  2830.         // removed. This will display: one ten
  2831.         MessageBox $listRemove(*two* $x)
  2832.  
  2833. mask is a standard wildcard mask, e.g. h?el?o, *test, bla*, *e*, etc.
  2834.  
  2835. [2.5.2.8] listReplace function
  2836. ------------------------------
  2837.  
  2838. Usage: $listReplace(start end element list)
  2839.  
  2840. Replaces the elements in list from start to end with element. Examples:
  2841.  
  2842.         @ $x = zero one two three four
  2843.         // This will display: zero X four
  2844.         MessageBox $listReplace(1 3 X $x)
  2845.  
  2846.         // This will display: zero "VIRC SCRIPT" four
  2847.         MessageBox $listReplace(1 3 "VIRC SCRIPT" $x)
  2848.  
  2849. Notice how this function replaces the elements specified with one element only.
  2850. The last string returned, zero "VIRC SCRIPT" four, has 3 elements: zero, VIRC
  2851. SCRIPT, and four. The string VIRC SCRIPT is inserted as one element.
  2852.  
  2853. [2.5.2.9] listSearch function
  2854. -----------------------------
  2855.  
  2856. Usage: $listSearch(mask list)
  2857.  
  2858. Returns another list which contains every element in list that is matched by
  2859. mask:
  2860.  
  2861.         @ $x = zero one two three four five six seven eight nine ten
  2862.         // This will display every element that has an e in it, i.e.
  2863.         // zero one three five seven eight nine ten
  2864.         MessageBox $listSearch(*e* $x)
  2865.  
  2866. mask is a standard wildcard mask, e.g. h?el?o, *test, bla*, *e*, etc.
  2867.  
  2868. [2.5.2.10] listSearchReplace function
  2869. -------------------------------------
  2870.  
  2871. Usage: $listSearchReplace(mask element list)
  2872.  
  2873. Returns another list which is the same as list, except that every element in
  2874. list that matches mask is replaced by the element specified. Examples:
  2875.  
  2876.         @ $x = zero one two three four five six seven eight nine ten
  2877.         // This will display: X X two X four X six X X X X
  2878.         MessageBox $listSearchReplace(*e* X $x)
  2879.  
  2880.         // This will make any occurrences of your nick in $y appear in bold
  2881.         @ $y = $listSearchReplace($N \b$N\b $y)
  2882.  
  2883. [2.5.2.11] listSplit function
  2884. -----------------------------
  2885.  
  2886. Usage: $listSplit(delimiter list)
  2887.  
  2888. Returns another list whose elements are delimited by the delimiter specified in
  2889. the list specifed. Example:
  2890.  
  2891.         @ $x = jimc.demon.co.uk
  2892.         // This will display: jimc demon co uk
  2893.         MessageBox $listSplit(. $x)
  2894.  
  2895.         @ $x = blah.blah test.test
  2896.         // Lists like these are handled correctly too. When delimited by a .
  2897.         // this list contains 3 elements only, blah, "blah test", and test.
  2898.         // So, this will display: blah "blah test" test
  2899.         MessageBox $listSplit(. $x)
  2900.  
  2901. [2.5.3] Set manipulation functions
  2902. ----------------------------------
  2903.  
  2904. V96 0.82 and above support sets, a very powerful feature similar to Delphi's
  2905. set capability. ObjectVS set properties are supported (see OBJECTVS.TXT), but
  2906. sets work well in regular VS without objects too.
  2907.  
  2908. Basically, a set can contain one or more elements, each which is one word. It's
  2909. as simple as that. For example, consider this data:
  2910.  
  2911.         Patricia        - Female, long dark hair, brown eyes, married
  2912.         Mark            - Male, short dark hair, blue eyes, not married
  2913.         Sarah           - Female, short red hair, black eyes, not married
  2914.  
  2915. You could represent this data in VS easily by use of sets:
  2916.  
  2917.         @ $Patricia = [sexFemale,hairLong,hairDark,eyesBrown,msMarried]
  2918.         @ $Mark = [sexMale,hairShort,hairDark,eyesBlue]
  2919.         @ $Sarah = [sexFemale,hairShort,hairRed,eyesBlack]
  2920.  
  2921. Note that all sets are surrounded by []'s and each set element is separated
  2922. from the next by a comma.
  2923.  
  2924. Once $Patricia and $Mark are defined, you can use, for example, the ISINSET
  2925. function as follows:
  2926.  
  2927.         $IsInSet([sexMale] $Mark)                       == 1
  2928.         $IsInSet([sexFemale,eyesBrown] $Patricia)       == 1
  2929.         $IsInSet([sexFemale,hairDark] $Sarah)           == 0
  2930.  
  2931. If Sarah dyes her hair black and grows it long, the ADDTOSET and REMOVEFROMSET
  2932. functions can be used:
  2933.  
  2934.         @ $Sarah = $RemoveFromSet($Sarah [hairShort,hairRed])
  2935.         @ $Sarah = $AddToSet($Sarah [hairLong,hairBlack])
  2936.  
  2937. On IRC, of course, you'd hardly ever represent personal information using sets.
  2938. :) What sets are very useful for is for storing user flags, for example:
  2939.  
  2940.         @s $userflags.$nick = [AutoOp,Protected,OnUserlist]
  2941.  
  2942. Then when a user joins a channel you could use something like this to auto-op
  2943. them:
  2944.  
  2945.         if ($IsInSet([AutoOp] $userflags.$nick))
  2946.            Mode +o $nick
  2947.         endif
  2948.  
  2949. Or a set could be used to hold a list of nicknames for some purpose - the
  2950. possibilities are practically endless.
  2951.  
  2952. Anyway. Now I'll document these set functions individually.
  2953.  
  2954. [2.5.3.1] IsInSet function
  2955. --------------------------
  2956.  
  2957. Usage: $IsInSet(set1 set2)
  2958.  
  2959. Returns 1 if every element in set1 is also in set2, and 0 otherwise.
  2960.  
  2961. [2.5.3.2] AddToSet function
  2962. ---------------------------
  2963.  
  2964. Usage: $AddToSet(set1 set2)
  2965.  
  2966. Additionally combines set1 and set2, and returns a new set containing all the
  2967. elements in both set1 and set2.
  2968.  
  2969. Note that ADDTOSET also cleans up the set, removing any spaces and duplicate
  2970. items. Hence it's sometimes useful to use ADDTOSET with set1 or set2 as an
  2971. empty set [] to clean it up, for example:
  2972.  
  2973.         @ $x = [     blue,      BLACK,    blAck, green         ]
  2974.         @ $y = $AddToSet([] $x)
  2975.  
  2976. $y will now contain [blue,BLACK,green]. Spaces and duplicate items (BLACK and
  2977. blAck, set operations are case-insensitive) have been removed.
  2978.  
  2979. [2.5.3.3] RemoveFromSet function
  2980. --------------------------------
  2981.  
  2982. Usage: $RemoveFromSet(set1 set2)
  2983.  
  2984. Returns a new set containing all the items in set1 that are not also in set2.
  2985.  
  2986. Note that REMOVETOSET also cleans up the set. For more information on cleaning
  2987. sets, see the note at the bottom of the ADDTOSET function above.
  2988.  
  2989. [2.5.4] Alias/event manipulation functions
  2990. ------------------------------------------
  2991.  
  2992. [2.5.4.1] AliasExists function
  2993. ------------------------------
  2994.  
  2995. Usage: $aliasexists(name)
  2996.  
  2997. Returns 1 if the alias name exists, and 0 if it does not.
  2998.  
  2999. [2.5.4.2] EventExists function
  3000. ------------------------------
  3001.  
  3002. Usage: $eventexists(name)
  3003.  
  3004. Returns 1 if the event name exists, and 0 if it does not.
  3005.  
  3006. [2.5.4.3] IsEventEnabled function
  3007. ---------------------------------
  3008.  
  3009. Usage: $iseventenabled(event)
  3010.  
  3011. Returns 1 if event is enabled (events are enabled by default), and 0 if event
  3012. is disabled (e.g. by the DISABLEEVENT command).
  3013.  
  3014. [2.5.5] Formatted text output functions
  3015. ---------------------------------------
  3016.  
  3017. [2.5.5.1] Bitmap function
  3018. -------------------------
  3019.  
  3020. Usage: $bitmap(filename)
  3021.  
  3022. This function loads a bitmap and returns a handle to it that can be used with
  3023. the TextOutBitmap command to display a line of text containing a bitmap to the
  3024. left of the text. At present, only 13x13 bitmaps (in the standard Windows BMP
  3025. format) are supported. Trying to use a larger or a smaller bitmap will cause
  3026. problem. The bottom left-hand pixel of the bitmap is used as the transparency
  3027. colour.
  3028.  
  3029. In addition, there are a number of built-in bitmaps. They have the following
  3030. "filenames":
  3031.  
  3032.         _join.bmp
  3033.         _part.bmp
  3034.         _quit.bmp
  3035.         _mode.bmp
  3036.         _face.bmp
  3037.  
  3038. If you use one of these bitmaps, they will be loaded from within the V97 EXE,
  3039. and don't need to be present on disk.
  3040.  
  3041. One thing is worth stressing. Because it would be extremely slow for a bitmap
  3042. to be loaded from disk each time it is displayed, bitmaps loaded with this
  3043. function are cached. If you load them again, the bitmap is retrieved from the
  3044. cache and isn't actually loaded from disk again. Therefore, if you change the
  3045. bitmap on disk, the old bitmap will still be used. To get around this, you can
  3046. use the FlushBitmapCache command to clear the bitmap caches. All bitmaps will
  3047. then be reloaded from disk.
  3048.  
  3049. Examples:
  3050.  
  3051.         // Display a line of text using a built-in bitmap
  3052.         TextOutBitmap > #virc clBlack $bitmap(_join.bmp) Welcome to #virc!
  3053.  
  3054.         // Display a line of text using a bitmap loaded from disk
  3055.         TextOutBitmap > #virc clBlack $bitmap(example.bmp) Welcome to #virc!
  3056.  
  3057. [2.5.6] Time and clock functions
  3058. --------------------------------
  3059.  
  3060. [2.5.6.1] CTime function
  3061. ------------------------
  3062.  
  3063. Usage: $ctime()
  3064.  
  3065. Used to calculate time intervals, measured in seconds. The actual value
  3066. returned is the number of seconds that Windows has been running, although this
  3067. may change in the future and cannot be relied upon. The number returned by
  3068. $ctime() increases by 1 every second. For example:
  3069.  
  3070.         @ $x = $ctime()
  3071.         for (@ $i = 0; $i < 1000; @ $i = $($i + 1))
  3072.           Yield
  3073.         endfor
  3074.         TextOut clBlue *** An empty 1000-iteration for loop takes $($ctime() - $x) seconds to complete.
  3075.  
  3076. Notice how $ctime() is used here to calculate a time interval - the actual
  3077. meaning of the value returned by $ctime() is insignificant.
  3078.  
  3079. The $ctime() function can also be used as a timer. For example, to wait for
  3080. 20 seconds before quitting V97, you could use the following code:
  3081.  
  3082.         @ $x = $ctime()
  3083.         while ($ctime() - $x) < 20
  3084.           Yield
  3085.         endwhile
  3086.         Exit
  3087.  
  3088. [2.5.6.2] Date function
  3089. -----------------------
  3090.  
  3091. Usage: $date()
  3092.  
  3093. Returns the current system date in default system format. This format is
  3094. determined by your Windows locale (internationalization) settings, and may be
  3095. something like 17th June 1996.
  3096.  
  3097. [2.5.6.3] DecodeInterval function
  3098. ---------------------------------
  3099.  
  3100. Usage: $decodeinterval(integer)
  3101.  
  3102. Converts the integer supplied as the parameter to a human-readable time
  3103. interval. For example:
  3104.  
  3105.         $decodeinterval(38) = 38 seconds
  3106.         $decodeinterval(60) = 1 minute
  3107.         $decodeinterval(61) = 1 minute 1 second
  3108.         $decodeinterval(3728) = 1 hour 2 minutes 8 seconds
  3109.  
  3110. [2.5.6.4] DecodePingInterval function
  3111. -------------------------------------
  3112.  
  3113. Usage: $decodepinginterval(integer)
  3114.  
  3115. Converts the ping-encoded integer specified to a human-readable time interval.
  3116. This function is only useful to decode received pings. To decode normal time
  3117. intervals, use the DECODEINTERVAL function.
  3118.  
  3119. [2.5.6.5] IdleMTime function
  3120. ----------------------------
  3121.  
  3122. Usage: $idlemtime()
  3123.  
  3124. Returns the amount of time the user has been idle for in milliseconds. The same
  3125. as $idletime(), only returns a value in milliseconds rather than seconds.
  3126.  
  3127. [2.5.6.6] IdleTime function
  3128. ---------------------------
  3129.  
  3130. Usage: $idletime()
  3131.  
  3132. Returns the amount of time the user has been idle for in seconds. Can be used
  3133. to implement auto-away scripts. For example, the following code will wait until
  3134. the user has been idle for 2 minutes (120 seconds) and will then set him away:
  3135.  
  3136.         while ($idletime() < 120)
  3137.           Yield
  3138.         endwhile
  3139.         Away Automatically set away after 2 minutes
  3140.  
  3141. [2.5.6.7] MTime function
  3142. ------------------------
  3143.  
  3144. Usage: $mtime()
  3145.  
  3146. Used to calculate time intervals, measured in milliseconds. Use for measuring
  3147. time intervals. The number returned by $mtime() increases by 1 every
  3148. millisecond.
  3149.  
  3150. [2.5.6.8] Time function
  3151. -----------------------
  3152.  
  3153. Usage: $time(format)
  3154.  
  3155. Returns the current system time in a human-readable format (hour:minute:second
  3156. AM/PM by default). For example, $time() may return 11:52:48 AM. If you wish,
  3157. you may specify an optional format string to format the date/time in any way
  3158. you wish. Valid format specifiers are:
  3159.  
  3160.         d       - Day of the month in numeric format, with no trailing zero (e.g. 7, 23)
  3161.         dd      - Day of the month in numeric format, with trailing zero if necessary (e.g. 07, 23)
  3162.         ddd     - Day of the week in short format (e.g. Sat)
  3163.         dddd    - Day of the week in long format (e.g. Saturday)
  3164.         m       - Month in numeric format, with no trailing zero (e.g. 6, 11)
  3165.         mm      - Month in numeric format, with trailing zero if necessary (e.g. 06, 11)
  3166.         mmm     - Month in short format (e.g. Jan)
  3167.         mmmm    - Month in long format (e.g. January)
  3168.         yy      - Year in short numeric format (e.g. 97)
  3169.         yyy     - Year in long numeric format (e.g. 1997)
  3170.  
  3171.         h       - Hour of the day in numeric format, with no trailing zero (e.g. 5, 16)
  3172.         hh      - Hour of the day in numeric format, with trailing zero if necessary (e.g. 05, 16)
  3173.         n       - Minute in numeric format, with no trailing zero (e.g. 3, 34)
  3174.         nn      - Minute in numeric format, with trailing zero if necessary (e.g. 03, 34)
  3175.         s       - Second in numeric format, with no trailing zero (e.g. 9, 46)
  3176.         ss      - Second in numeric format, with trailing zero if necessary (e.g. 09, 46)
  3177.         A/P     - A if the time is AM, P if the time is PM
  3178.         AM/PM   - AM if the time is AM, PM is the time is PM
  3179.  
  3180. Note that if A/P or AM/PM are specified, the time is given in 12-hour format,
  3181. otherwise, it is given in 24-hour format.
  3182.  
  3183. For example:
  3184.  
  3185.         $time(dd/mm/yy hh:nn:ss) - might return 12/07/96 19:21:18
  3186.         $time(dd/mm/yy hh:nn:ss AM/PM) - might return 12/07/96 07:21:18 PM
  3187.         $time(ss) - might return 18
  3188.  
  3189. [2.5.6.9] TimeConnected function
  3190. --------------------------------
  3191.  
  3192. Usage: $timeconnected()
  3193.  
  3194. Returns the number of seconds that you've been connected to the server for. If
  3195. you're not currently connected to the server, this will return 0. Usefully, the
  3196. value of this function is not reset to 0 until after <OnDisconnect> has been
  3197. fired. Therefore, your script can report the total time connected to the server
  3198. when the user disconnects by adding a line of code to the <OnDisconnect>
  3199. event.
  3200.  
  3201. [2.5.6.10] UnixTime function
  3202. ----------------------------
  3203.  
  3204. Usage: $unixtime(unixtime)
  3205.        $unixtime(unixtime format)
  3206.  
  3207. Converts the unixtime specified to human-readable format. Many IRC server
  3208. responses return times in unixtime (otherwise known as UTC time) format, which
  3209. is currently a number around 850000000. The unixtime value is the number of
  3210. seconds since 1st January 1970 00:00:00 AM GMT, and is the value returned by
  3211. the C time() function. If you do not specify the format parameter, the date
  3212. and time will be displayed in the same way as the TIME function displays dates
  3213. and times by default. See the TIME function for information on format strings.
  3214.  
  3215. [2.5.7] File I/O functions
  3216. --------------------------
  3217.  
  3218. [2.5.7.1] FileExists function
  3219. -----------------------------
  3220.  
  3221. Usage: $fileexists(filename)
  3222.  
  3223. Returns true (1) if filename exists, otherwise returns false (0).
  3224.  
  3225. [2.5.7.2] GetCurrentDir function
  3226. --------------------------------
  3227.  
  3228. Usage: $getcurrentdir()
  3229.  
  3230. Returns the current directory on the current drive. The directory name returned
  3231. by this function ALWAYS ends in a bashslash (\).
  3232.  
  3233. [2.5.7.3] GetFileSize function
  3234. ------------------------------
  3235.  
  3236. Usage: $getfilesize(filename)
  3237.  
  3238. Returns the size, in bytes, of filename. If filename doesn't exist, or cannot
  3239. be accessed, this function will return -1 (it returned 0 in versions prior to
  3240. 1.00rc5b).
  3241.  
  3242. [2.5.7.4] GetFileDateTime function
  3243. ----------------------------------
  3244.  
  3245. Usage: $getfiledatetime(filename)
  3246.        $getfiledatetime(filename format)
  3247.  
  3248. Returns filename's date and/or time. If format is not specified, the filename's
  3249. date and time will be returned in the same format as the TIME function returns
  3250. system times. You may also specify format to format the date and time
  3251. information in any way you wish. See the TIME function for information on
  3252. format strings.
  3253.  
  3254. [2.5.7.5] GetLinesInFile function
  3255. ---------------------------------
  3256.  
  3257. Usage: $getlinesinfile(filename)
  3258.  
  3259. Returns the number of lines in filename. If filename doesn't exist, the
  3260. function will return -1.
  3261.  
  3262. [2.5.7.6] GetPath function
  3263. --------------------------
  3264.  
  3265. Usage: $getpath(id)
  3266.  
  3267. Returns one of the stock ViRC '97 paths (see Client setup/Paths). id can be one
  3268. of the following:
  3269.  
  3270.         virc                    - returns the base ViRC '97 directory
  3271.         upload                  - returns the V97 upload directory
  3272.         download                - returns the V97 download directory
  3273.         script                  - returns the V97 script directory
  3274.         sound                   - returns the V97 sound directory
  3275.  
  3276. [2.5.7.7] PathExists function
  3277. -----------------------------
  3278.  
  3279. Usage: $pathexists(path)
  3280.  
  3281. Returns 1 if path exists, and 0 otherwise.
  3282.  
  3283. [2.5.7.8] RandomRead function
  3284. -----------------------------
  3285.  
  3286. Usage: $randomread(file)
  3287.  
  3288. Returns a randomly-selected line from file. This is useful for quote or slap
  3289. scripts.
  3290.  
  3291. [2.5.7.9] ReadLine function
  3292. ---------------------------
  3293.  
  3294. Usage: $readline(linenum filename)
  3295.  
  3296. Returns line number linenum from filename. For example, $readline(1 blah.txt)
  3297. will return the 1st line from the file blah.txt. If you specify an invalid
  3298. line number, the function returns an empty string.
  3299.  
  3300. [2.5.8] Registry I/O functions
  3301. ------------------------------
  3302.  
  3303. [2.5.8.1] ReadRegistry function
  3304. -------------------------------
  3305.  
  3306. Usage: $readregistry("section" key)
  3307.        $readregistry("section" key default)
  3308.  
  3309. Returns the value of key from the registry section "section", located under
  3310. the ViRC '97 key (e.g. having a section of "YyzScript" would write to
  3311. HKEY_CURRENT_USER\Software\MeGALiTH Software\Visual IRC 96\YyzScript. If you
  3312. wish, you may also specify a default value which is returned if the registry
  3313. value you're trying to read doesn't exist. You cannot read outside the ViRC '97
  3314. key in the registry. This is a conscious design decision to ensure maximum
  3315. security (a malicious script cannot read private parts of your registry and
  3316. send them over IRC).
  3317.  
  3318. [2.5.8.2] GetSetting function
  3319. -----------------------------
  3320.  
  3321. Usage: $getsetting(section value)
  3322.  
  3323. This is a very powerful function which allows a script to obtain any ViRC '97
  3324. user setting that it's stored in the registry. For example, the default event
  3325. library that comes with V97, DEFAULT.LIB, uses this function to determine
  3326. whether to output text in a query window or not, depending on whether the user
  3327. has chosen to use a query window or not in the Options tab of the Client Setup
  3328. dialog.
  3329.  
  3330. The best way to find the values for section and value is to load up REGEDIT (it
  3331. comes with Windows 95 and NT) and to look in
  3332. HKEY_CURRENT_USER/Software/MeGALiTH Software/Visual IRC '97. All available
  3333. sections are visible there.
  3334.  
  3335. Examples:
  3336.  
  3337.         $getsetting(Options QueryEnabled)
  3338.         $getsetting(Options AutoRejoin)
  3339.         $getsetting(SOCKS setup Enabled)
  3340.         $getsetting(IDENTD setup Port)
  3341.  
  3342. [2.5.9] Common dialogs
  3343. ----------------------
  3344.  
  3345. [2.5.9.1] OpenDialog function
  3346. -----------------------------
  3347.  
  3348. Usage: $opendialog(title|filespecdescription|filespec ...)
  3349.        $opendialog(title)
  3350.  
  3351. Displays a COMDLG32.DLL standard file open dialog, which has the title title,
  3352. and displays files of type filespecdescription and filespec. If
  3353. filespecdescription and filespec are omitted, all files (*.*) are displayed.
  3354. Use of this function is best illustrated with a few examples:
  3355.  
  3356.         // Prompts the user for a script and /loads it
  3357.         Load $opendialog(Select a ViRCScript script to load|ViRCScript files (*.vsc)|*.vsc)
  3358.  
  3359.         // Prompts the user to select any file, and assigns its name to $x
  3360.         @ $x = $opendialog(Select any file)
  3361.  
  3362.         // Prompts the user for a .TXT or a .DOC file, and DCC SENDs it to the nick abc123
  3363.         DCC Send abc123 $opendialog(Select a text file|Text files|*.txt|Word documents|*.doc)
  3364.  
  3365. If the user presses the Cancel button on the dialog, an empty string is
  3366. returned, for example:
  3367.  
  3368.         @ $x = $opendialog(blah blah blah)
  3369.         if ([$x] == [])
  3370.            MessageBox You must select a filename!!
  3371.            Halt
  3372.         endif
  3373.  
  3374. [2.5.9.2] OpenPictureDialog function
  3375. ------------------------------------
  3376.  
  3377. Usage: $openpicturedialog(title|filespecdescription|filespec ...)
  3378.        $openpicturedialog(title)
  3379.  
  3380. Identical to the OpenDialog function, except that this dialog has a built-in
  3381. picture viewer, currently supporting BMP, ICO, WMF and JPG files. You can use
  3382. this function to write a poor man's picture viewer in ViRCScript.
  3383.  
  3384. [2.5.9.3] SaveDialog function
  3385. -----------------------------
  3386.  
  3387. Usage: $savedialog(title|filespecdescription|filespec ...)
  3388.        $savedialog(title)
  3389.  
  3390. Very similar to the OPENDIALOG function documented above, except the dialog has
  3391. a Save button instead of an Open button. In addition, if the file the user
  3392. selects already exists, they will be prompted whether they wish to overwrite
  3393. it. If no file is selected, the function returns an empty string.
  3394.  
  3395. For examples, see the OPENDIALOG function documented above.
  3396.  
  3397. [2.5.9.4] SavePictureDialog function
  3398. ------------------------------------
  3399.  
  3400. Usage: $savepicturedialog(title|filespecdescription|filespec ...)
  3401.        $savepicturedialog(title)
  3402.  
  3403. Identical to the SaveDialog function, except that this dialog has a built-in
  3404. picture viewer, currently supporting BMP, ICO, WMF and JPG files.
  3405.  
  3406. [2.5.10] IRC-specific functions
  3407. -------------------------------
  3408.  
  3409. [2.5.10.1] ActiveWindow function
  3410. --------------------------------
  3411.  
  3412. Usage: $activewindow()
  3413.  
  3414. Returns the window that currently has the focus. If a channel window currently
  3415. has the focus, this function will return the name of the channel. If a query
  3416. window currently has the focus, this function will return the nick of the
  3417. query window. If the server window currently has the focus, this function will
  3418. return . (a period).
  3419.  
  3420. Remember that, in an alias, $C contains the name of the window that the alias
  3421. was executed in, but in an event (which is really just fired when any line of
  3422. text is received from the server), $C has no value, but $activewindow() will
  3423. always return the correct value. Useful if you want to write some text to the
  3424. window the user currently has the focus set to (so he/she won't miss the
  3425. text!!).
  3426.  
  3427. [2.5.10.2] ChannelCount function
  3428. --------------------------------
  3429.  
  3430. Usage: $channelcount()
  3431.  
  3432. Returns the number of open channels.
  3433.  
  3434. [2.5.10.3] Channels function
  3435. ----------------------------
  3436.  
  3437. Usage: $channels(num)
  3438.  
  3439. Returns the name of open channel number num. For example, if you have one
  3440. channel open, #quake, $channels(1) will return #quake. If the channel number
  3441. num specified does not exist, the function will return nothing.
  3442.  
  3443. [2.5.10.4] ChannelList function
  3444. -------------------------------
  3445.  
  3446. Usage: $channellist()
  3447.  
  3448. Returns a list of all the channels you're on. For example, if you're on #quake,
  3449. #virc, and #polska, this function would return:
  3450.  
  3451.         #quake #virc #polska
  3452.  
  3453. [2.5.10.5] CurrentServer_ActiveWindow function
  3454. ----------------------------------------------
  3455.  
  3456. Usage: $currentserver_activewindow()
  3457.  
  3458. This horribly-named function is exactly the same as $activewindow(), except for
  3459. the fact that, if the active window does NOT belong to the current server
  3460. connection (e.g. if the active window is a channel from a different server to
  3461. the one that the alias/event was executed in), the function will return . as if
  3462. the active window was the server notices window for the current server. If you
  3463. don't understand this, you won't have to use this function. :)
  3464.  
  3465. [2.5.10.6] GetAddress function
  3466. ------------------------------
  3467.  
  3468. Usage: $getaddress(nick)
  3469.  
  3470. Gets the email (user@host) address of nick. If the address cannot be retrieved
  3471. for some reason, the function will return unknown@unknown.
  3472.  
  3473. Recent versions of ViRC '97 maintain a cache called the IAL (Internal Address
  3474. List) which keeps track of the user@host addresses of nicks on channels. If any
  3475. address is in the IAL, it will be retrieved immediately, and the server will
  3476. not be queried for it again. You may manually add nick!user@host masks with the
  3477. AddToIAL command. For more information on the IAL, see the AddToIAL command.
  3478.  
  3479. [2.5.10.7] GetBanLevel function
  3480. -------------------------------
  3481.  
  3482. Usage: $getbanlevel(mask)
  3483.  
  3484. Returns the banlevel of mask in your banlist. If the user cannot be found in
  3485. the banlist, the function will return 0.
  3486.  
  3487. [2.5.10.8] GetCustomLevel function
  3488. ----------------------------------
  3489.  
  3490. Usage: $getcustomlevel(mask)
  3491.  
  3492. Returns the customlevel of mask in your userlist. If the user cannot be found
  3493. in the userlist, the function will return an empty string.
  3494.  
  3495. [2.5.10.9] GetLag function
  3496. --------------------------
  3497.  
  3498. Usage: $getlag()
  3499.  
  3500. Gets the current lag-ness of the active server connection. The lag is returned
  3501. in tenths of seconds (e.g. 10 means 1 second of lag). If the lag is unknown,
  3502. this function will return -1.
  3503.  
  3504. [2.5.10.10] GetUser function
  3505. ----------------------------
  3506.  
  3507. Usage: $getuser()
  3508.  
  3509. If the -user parameter was specified on V97's command line, this function
  3510. returns the name of the user. If -user was not specified, this function returns
  3511. an empty string.
  3512.  
  3513. [2.5.10.11] GetUserLevel function
  3514. --------------------------------
  3515.  
  3516. Usage: $getuserlevel(mask)
  3517.  
  3518. Returns the userlevel of mask in your userlist. For example, if
  3519. *!*blah@*hah.com is in your userlist with level 3,
  3520. $getuserlevel(user!nablah@spahah.com) would return 3. If the user cannot be
  3521. found in the userlist, the function will return 0.
  3522.  
  3523. [2.5.10.12] GetProtLevel function
  3524. --------------------------------
  3525.  
  3526. Usage: $getprotlevel(mask)
  3527.  
  3528. Returns the protlevel of mask in your protlist. If the user cannot be found in
  3529. the protlist, the function will return 0.
  3530.  
  3531. [2.5.10.13] IsDCCChatting function
  3532. ----------------------------------
  3533.  
  3534. Usage: $isdccchatting(nick)
  3535.  
  3536. Returns 1 if a DCC Chat connection is currently open with nick, and 0 if no
  3537. DCC Chat connection is currently open with nick.
  3538.  
  3539. [2.5.10.14] IsOn function
  3540. -------------------------
  3541.  
  3542. Usage: $ison(nick channel)
  3543.  
  3544. Returns true (1) if nick is on channel, otherwise returns false (0). Example:
  3545.  
  3546.         if $ison(MeGALiTH #quake)
  3547.            Msg MeGALiTH Hi there!!
  3548.         endif
  3549.  
  3550. [2.5.10.15] IsOp function
  3551. -------------------------
  3552.  
  3553. Usage: $isop(nick channel)
  3554.  
  3555. Returns true (1) if nick is an op on channel. If nick is a non-op on channel,
  3556. or if nick is not on channel, returns false (0).
  3557.  
  3558. [2.5.10.16] IsQuerying function
  3559. -------------------------------
  3560.  
  3561. Usage: $isquerying(nick)
  3562.  
  3563. Returns 1 if a query window is currently open for nick, and 0 otherwise.
  3564.  
  3565. [2.5.10.17] IsVoice function
  3566. ----------------------------
  3567.  
  3568. Usage: $isvoice(nick channel)
  3569.  
  3570. Returns 1 if nick, a non-op, is allowed to speak on the moderated channel
  3571. channel, and 0 if nick cannot speak, if nick is not on a moderated channel, if
  3572. nick is not on channel, or if nick is opped.
  3573.  
  3574. In order to find out if any user, op or otherwise, can speak on a moderated
  3575. channel, use something like:
  3576.  
  3577.         if ($isop($nick $channel) || $isvoice($nick $channel))
  3578.            // User can speak ...
  3579.         endif
  3580.  
  3581. [2.5.10.18] IsWatchdogActive function
  3582. -------------------------------------
  3583.  
  3584. Usage: $iswatchdogactive()
  3585.  
  3586. Returns 1 if the watchdog is currently enabled (and hence the main V97 window
  3587. is hidden), and 0 if the watchdog is currently disabled (the normal state -
  3588. the main V97 window is visible).
  3589.  
  3590. [2.5.10.19] Nicks function
  3591. --------------------------
  3592.  
  3593. Usage: $nicks(channel num)
  3594.  
  3595. Returns the num'th user on channel. For example, $nicks(#quake 45) will return
  3596. the nick of the 45th user on channel #quake (the list is sorted
  3597. alphabetically, with ops at the top, followed by peons). If channel doesn't
  3598. exist, or there is no user at num (i.e. if num is less than 1 or greater than
  3599. $nickcount), the function will return nothing.
  3600.  
  3601. [2.5.10.20] NickCount function
  3602. ------------------------------
  3603.  
  3604. Usage: $nickcount(channel)
  3605.  
  3606. Returns the number of users on channel. If channel doesn't exist, the function
  3607. will return 0.
  3608.  
  3609. [2.5.10.21] NickList function
  3610. -----------------------------
  3611.  
  3612. Usage: $nicklist(channel)
  3613.  
  3614. Returns a list of all the users on channel. For example, if nick1, nick2 and
  3615. nick3 are on channel, this function would return:
  3616.  
  3617.         nick1 nick2 nick3
  3618.  
  3619. [2.5.10.22] Ops function
  3620. ------------------------
  3621.  
  3622. Usage: $ops(channel num)
  3623.  
  3624. Returns the num'th op on channel. For example, $ops(#quake 3) will return the
  3625. nick of the 3rd op on channel #quake (the list is sorted alphabetically). If
  3626. channel doesn't exist, or there is no op at num (i.e. if num is less than 1 or
  3627. greater than $opcount), the function will return nothing.
  3628.  
  3629. [2.5.10.23] OpCount function
  3630. ----------------------------
  3631.  
  3632. Usage: $opcount(channel)
  3633.  
  3634. Returns the number of ops on channel. If channel doesn't exist, or if there are
  3635. no ops, the function will return 0.
  3636.  
  3637. [2.5.10.24] OpList function
  3638. ---------------------------
  3639.  
  3640. Usage: $oplist(channel)
  3641.  
  3642. Returns a list of all the ops on channel. For example, if nick1, nick2 and
  3643. nick3 are ops on channel, this function would return:
  3644.  
  3645.         nick1 nick2 nick3
  3646.  
  3647. [2.5.10.25] OpStrip function
  3648. ----------------------------
  3649.  
  3650. Usage: $opstrip(nick)
  3651.  
  3652. Strips any trailing @ or + from nick. If, for example, you are using
  3653. the SELECTEDNICK function to get the currently-selected nick in a channel nicks
  3654. list, you must use the OPSTRIP function on the nick before performing any
  3655. operations to make sure that the op (@) and/or voice (+) prefixes are removed.
  3656.  
  3657. [2.5.10.26] Peons function
  3658. --------------------------
  3659.  
  3660. Usage: $peons(channel num)
  3661.  
  3662. Returns the num'th peon (non-op) on channel. For example, $peons(#quake 19)
  3663. will return the nick of the 19th peon on channel #quake (the list is sorted
  3664. alphabetically). If channel doesn't exist, or there is no peon at num (i.e. if
  3665. num is less than 1 or greater than $peoncount), the function will return
  3666. nothing.
  3667.  
  3668. [2.5.10.27] PeonCount function
  3669. ------------------------------
  3670.  
  3671. Usage: $peoncount(channel)
  3672.  
  3673. Returns the number of peons (non-ops) on channel. If channel doesn't exist, or
  3674. if there are no peons, the function will return 0.
  3675.  
  3676. [2.5.10.28] PeonList function
  3677. -----------------------------
  3678.  
  3679. Usage: $peonlist(channel)
  3680.  
  3681. Returns a list of all the peons (non-ops) on channel. For example, if nick1,
  3682. nick2 and nick3 are peons on channel, this function would return:
  3683.  
  3684.         nick1 nick2 nick3
  3685.  
  3686. [2.5.10.29] QueryList function
  3687. ------------------------------
  3688.  
  3689. Usage: $querylist()
  3690.  
  3691. Returns a list of all the users you have a query (private message) window open
  3692. to. For example, if you have a query window open with nick1, nick2 and nick3,
  3693. this function would return:
  3694.  
  3695.         nick1 nick2 nick3
  3696.  
  3697. [2.5.10.30] SelectedNick function
  3698. ---------------------------------
  3699.  
  3700. Usage: $selectednick(channel)
  3701.  
  3702. Returns the nick selected in channel's nicks list. If channel is not a valid
  3703. channel window, or if no nick is selected in channel's nicks list, this
  3704. function will return an empty string. The nick returned may be prefixed with
  3705. op (@) and/or voice (+) flags, which should be stripped off with the OPSTRIP
  3706. function before the nick can be used with other IRC commands (e.g. MODE, KICK
  3707. etc.).
  3708.  
  3709. [2.5.10.31] VoiceList function
  3710. ------------------------------
  3711.  
  3712. Usage: $voicelist(channel)
  3713.  
  3714. Returns a list of all the users who can speak (excluding ops) on the moderated
  3715. channel specified as the parameter. For example, if nick1, nick2 and nick3 are
  3716. +v (can speak) on the moderated channel specified as the parameter, this
  3717. function would return:
  3718.  
  3719.         nick1 nick2 nick3
  3720.  
  3721. [2.5.11] XDCC (file offer server) functions
  3722. -------------------------------------------
  3723.  
  3724. [2.5.11.1] GetXDCCPackCount function
  3725. ------------------------------------
  3726.  
  3727. Usage: $getxdccpackcount()
  3728.  
  3729. Returns the number of XDCC packs defined in Client setup/XDCC. If no packs are
  3730. defined, this function will return 0.
  3731.  
  3732. [2.5.11.2] GetXDCCPackDesc function
  3733. -----------------------------------
  3734.  
  3735. Usage: $getxdccpackdesc(pack)
  3736.  
  3737. Returns the pack description for XDCC pack number pack. pack ranges from 1 to
  3738. the value returned by the GETXDCCPACKCOUNT function. If you specify an invalid
  3739. pack number, this function will return an empty string.
  3740.  
  3741. [2.5.11.3] GetXDCCPackFileCount function
  3742. ----------------------------------------
  3743.  
  3744. Usage: $getxdccpackfilecount(pack)
  3745.  
  3746. Returns the number of files in XDCC pack number pack. pack ranges from 1 to the
  3747. value returned by the GETXDCCPACKCOUNT function. If you specify an invalid pack
  3748. number, this function will return 0.
  3749.  
  3750. [2.5.11.4] GetXDCCPackFiles function
  3751. ------------------------------------
  3752.  
  3753. Usage: $getxdccpackfiles(pack)
  3754.  
  3755. Returns a list of files in XDCC pack number pack. Quotes (") are placed around
  3756. each filename, and the filenames (which include a full path) are separated by
  3757. spaces. pack ranges from 1 to the value returned by the GETXDCCPACKCOUNT
  3758. function. If you specify an invalid pack number, this function will return an
  3759. empty string. The PARSE EXTENDED statement can then be used to separate the
  3760. file names.
  3761.  
  3762. [2.5.11.5] GetXDCCPackGets function
  3763. -----------------------------------
  3764.  
  3765. Usage: $getxdccpackgets(pack)
  3766.  
  3767. Returns the number of times XDCC pack number pack has been downloaded. pack
  3768. ranges from 1 to the value returned by the GETXDCCPACKCOUNT function. If you
  3769. specify an invalid pack number, this function will return 0.
  3770.  
  3771. [2.5.11.6] GetXDCCPackSize function
  3772. -----------------------------------
  3773.  
  3774. Usage: $getxdccpacksize(pack)
  3775.  
  3776. Returns the total size of all the files defined in XDCC pack number pack. pack
  3777. ranges from 1 to the value returned by the GETXDCCPACKCOUNT function. If you
  3778. specify an invalid pack number, this function will return 0.
  3779.  
  3780. [2.5.12] DCC (chat and file transfer) functions
  3781. -----------------------------------------------
  3782.  
  3783. [2.5.12.1] DCCChatList
  3784. ----------------------
  3785.  
  3786. Usage: $DCCChatList()
  3787.  
  3788. Returns a list of all active DCC Chat sessions (both incoming and outgoing).
  3789. The list is returned in the format of a list of =nick entries, which can then
  3790. be passed as parameters to commands that take a window ID, such as Min and
  3791. Max, or the OVS $MapObject() function (see OBJECTVS.TXT). For example, if
  3792. you're chatting to Amagosa and Mr2001, this function would return:
  3793.  
  3794.         =Amagosa =Mr2001
  3795.  
  3796. [2.5.12.2] DCCGetList
  3797. ---------------------
  3798.  
  3799. Usage: $DCCGetList()
  3800.  
  3801. Returns a list of all active DCC Get and TDCC Get sessions. The list is
  3802. returned in the format of a list of *[T]GET/nick/file entires, which can then
  3803. be passed as parameters to commands that take a window ID, such as Min and
  3804. Max, or the OVS $MapObject() function (see OBJECTVS.TXT), or the $GetDCC...()
  3805. functions detailed below. For example, if you're getting README.TXT from
  3806. Amagosa by DCC and VSCRIPT.TXT from Mr2001 by TDCC, this function would return:
  3807.  
  3808.         *GET/Amagosa/README.TXT *TGET/Mr2001/VSCRIPT.TXT
  3809.  
  3810. If file names contain a space, the entries will be surrounded in quotes, e.g.:
  3811.  
  3812.         "*GET/Atrox/long filename.txt"
  3813.  
  3814. The quotes will be removed when you use the list-handling functions, for
  3815. example, $listIndex(), to extract the list elements.
  3816.  
  3817. Note that the filename returned here is the actual filename of the file being
  3818. written to disk, which isn't necessarily the same as the original name of the
  3819. file (the user may have opted to rename the file before receiving it).
  3820.  
  3821. [2.5.12.3] DCCSendList
  3822. ----------------------
  3823.  
  3824. Returns a list of all active DCC Send and TDCC Send sessions. The list is
  3825. returned in the format of a list of *[T]SEND/nick/file entires, which can then
  3826. be passed as parameters to commands that take a window ID, such as Min and
  3827. Max, or the OVS $MapObject() function (see OBJECTVS.TXT), or the $GetDCC...()
  3828. functions detailed below. For example, if you're sending README.TXT to
  3829. Amagosa by DCC and VSCRIPT.TXT to Mr2001 by TDCC, this function would return:
  3830.  
  3831.         *SEND/Amagosa/README.TXT *TSEND/Mr2001/VSCRIPT.TXT
  3832.  
  3833. If file names contain a space, the entries will be surrounded in quotes, e.g.:
  3834.  
  3835.         "*SEND/Atrox/long filename.txt"
  3836.  
  3837. The quotes will be removed when you use the list-handling functions, for
  3838. example, $listIndex(), to extract the list elements.
  3839.  
  3840. Note that the filename returned here is the actual filename of the file being
  3841. written to disk, which isn't necessarily the same as the original name of the
  3842. file (the user may have opted to rename the file before receiving it).
  3843.  
  3844. [2.5.12.4] GetDCCSize
  3845. ---------------------
  3846.  
  3847. Usage: $GetDCCSize(dccwindow)
  3848.  
  3849. Returns the size of the file being transferred in dccwindow. dccwindow is a DCC
  3850. transfer window ID, as returned by the $DCCGetList() or $DCCSendList()
  3851. functions, as detailed above. For example, if the file README.TXT that's being
  3852. sent by DCC to Amagosa is 34078 bytes large,
  3853. $GetDCCSize(*SEND/Amagosa/README.TXT) will return:
  3854.  
  3855.         34078
  3856.  
  3857. [2.5.12.5] GetDCCSpeed
  3858. ---------------------
  3859.  
  3860. Usage: $GetDCCSpeed(dccwindow)
  3861.  
  3862. Returns the file transfer speed of the file being transferred in dccwindow.
  3863. dccwindow is a DCC transfer window ID, as returned by the $DCCGetList() or
  3864. $DCCSendList() functions, as detailed above. For example, if the file
  3865. README.TXT is being send by DCC to Amagosa at 2.86 kilobytes per second,
  3866. $GetDCCSpeed(*SEND/Amagosa/README.TXT) will return:
  3867.  
  3868.         2.86 kb/sec
  3869.  
  3870. [2.5.12.5] GetDCCPercent
  3871. ------------------------
  3872.  
  3873. Usage: $GetDCCPercent(dccwindow)
  3874.  
  3875. Returns the percentage complete (from 0 to 100) of the file being transferred
  3876. in dccwindow. dccwindow is a DCC transfer window ID, as returned by the
  3877. $DCCGetList() or $DCCSendList() functions, as detailed above. For example, if
  3878. the file README.TXT being received by TDCC from Amagosa is 44% complete,
  3879. $GetDCCPercent(*TGET/Amagosa/README.TXT) will return:
  3880.  
  3881.         44
  3882.  
  3883. [2.5.12.6] GetDCCProgress
  3884. -------------------------
  3885.  
  3886. Usage: $GetDCCProgress(dccwindow)
  3887.  
  3888. Returns the number of bytes sent or received of the file being transferred in
  3889. dccwindow. dccwindow is a DCC transfer window ID, as returned by the
  3890. $DCCGetList() or $DCCSendList() functions, as detailed above. For example, if
  3891. 24062 bytes of the file README.TXT being received by TDCC from Amagosa have
  3892. already been received, $GetDCCProgress(*TGET/Amagosa/README.TXT) will return:
  3893.  
  3894.         24062
  3895.  
  3896. [2.5.12.7] GetDCCTimeLeft
  3897. -------------------------
  3898.  
  3899. Usage: $GetDCCTimeLeft(dccwindow)
  3900.  
  3901. Returns the estimated time left to completion of the file being transferred in
  3902. dccwindow. dccwindow is a DCC transfer window ID, as returned by the
  3903. $DCCGetList() or $DCCSendList() functions, as detailed above. For example, if
  3904. the TDCC Send to Mr2001 of VSCRIPT.TXT is estimated to complete in 4 minutes
  3905. and 3 seconds, $GetDCCTimeLeft(*TSEND/Mr2001/VSCRIPT.TXT) will return:
  3906.  
  3907.         4 minutes and 3 seconds
  3908.  
  3909. [2.5.13] Inter-server communication functions
  3910. ---------------------------------------------
  3911.  
  3912. The functions detailed below, along with the OnServer command, allow your
  3913. scripts to send data to a different IRC server connection from what the script
  3914. was run in.
  3915.  
  3916. [2.5.13.1] CurrentServer function
  3917. ---------------------------------
  3918.  
  3919. Usage: $CurrentServer()
  3920.  
  3921. Returns the number of the active server connection. This number is the list
  3922. index of the active server connection in the list as returned by the
  3923. $ServerList() function. For example, if the first server in the list returned
  3924. by the $ServerList() function is the active server, this function will return
  3925. 0, and if the second server is active, this function will return 1, and so
  3926. forth.
  3927.  
  3928. Note that changing the active server connection MAY WELL CHANGE THE ORDER OF
  3929. THE ITEMS IN THE LIST RETURNED BY THE $ServerList() FUNCTION. For example, you
  3930. may find that, no matter what server connection is active, this function always
  3931. returns, say, 0. This may seem counter-intuitive, but remember that item 0 in
  3932. the server connection list has actually changed instead. Make sure that your
  3933. scripts do not rely on the order of the items in the $ServerList() list staying
  3934. constant between server connections - it won't.
  3935.  
  3936. [2.5.13.2] ServerCount function
  3937. -------------------------------
  3938.  
  3939. Usage: $ServerCount()
  3940.  
  3941. Returns the number of open server connections. For example, if you had 3 server
  3942. windows open, and 2 of them were connected, this function would return 2.
  3943.  
  3944. [2.5.13.3] ServerList function
  3945. ------------------------------
  3946.  
  3947. Usage: $ServerList()
  3948.  
  3949. Returns a list of all the servers you're connected to. For example, if you're
  3950. connected to irc.ionet.net port 6667 and efnet.demon.co.uk port 6666, this
  3951. function would return:
  3952.  
  3953.         irc.ionet.net:6667 efnet.demon.co.uk:6666
  3954.  
  3955. Note that changing the active server connection MAY WELL CHANGE THE ORDER OF
  3956. THE ITEMS IN THIS LIST. This may seem counter-intuitive, so make sure your
  3957. scripts do not rely on the order of the items in this list staying constant
  3958. between server connections - it won't.
  3959.  
  3960. [2.5.14] Miscellaneous functions
  3961. --------------------------------
  3962.  
  3963. [2.5.14.1] $? (text input dialog)
  3964. ---------------------------------
  3965.  
  3966. Usage: $?="prompt"
  3967.  
  3968. Prompts the user to enter some text, displaying prompt in the text entry dialog
  3969. box. This is similar to mIRC's $? "function".
  3970.  
  3971. In 0.91 and above, you may specify some text that appears in the input section
  3972. of the box by placing |text in prompt. For example, the following line of code
  3973. will prompt you for a channel name with #virc already in the input field of the
  3974. box:
  3975.  
  3976.         @l $channel = $?="Enter a channel to join:|#virc"
  3977.  
  3978. [2.5.14.2] DecodeIP function
  3979. ----------------------------
  3980.  
  3981. Usage: $decodeip(encodedip)
  3982.  
  3983. Converts encodedip (an unsigned long) into an IP address in a.b.c.d format. You
  3984. can use this function to convert encoded IP addresses (for example, in DCC
  3985. requests received from users) to user-readable format. Example:
  3986.  
  3987.         $decodeip(2660773201)           = 158.152.45.81
  3988.  
  3989. [2.5.14.3] DNS function
  3990. -----------------------
  3991.  
  3992. Usage: $dns(hostname)
  3993.  
  3994. Resolves hostname and returns the corresponding IP. If hostname cannot be
  3995. resolved for some reason (for example, if the hostname doesn't exit), the
  3996. function will return an empty string.
  3997.  
  3998.         $dns(megalith.co.uk) = 158.152.45.81
  3999.  
  4000. [2.5.14.4] EncodeIP function
  4001. ----------------------------
  4002.  
  4003. Usage: $encodeip(IP)
  4004.  
  4005. Encodes IP to unsigned long format. This lets you connect to an IP address and
  4006. send stuff via a DCC Chat connection, for example, just like telnet. For
  4007. example, my mail server is 194.217.242.145, so, in a script, you could use the
  4008. following line to start an SMTP connection with my mail server:
  4009.  
  4010.         CTCP $N DCC CHAT chat $encodeip(194.217.242.145) 25
  4011.  
  4012. By faking an incoming DCC Chat connection, this neat little trick lets you do
  4013. all sorts of things, like, for example, making raw connections to IRC servers
  4014. etc. without the use of the ObjectViRCScript TSockets class.
  4015.  
  4016. [2.5.14.5] GetAlias function
  4017. ----------------------------
  4018.  
  4019. Usage: $getalias(alias)
  4020.  
  4021. Returns the ViRCScript code of alias. Together with the SETALIAS command, the
  4022. GETALIAS function can be used to append lines of code to existing aliases.
  4023. Example:
  4024.  
  4025.         SetAlias DEOP = $getalias(deop)$char(13)Beep
  4026.  
  4027. This will add the command BEEP (preceded by a $char(13) - the new line
  4028. character) to the end of the DEOP alias.
  4029.  
  4030. [2.5.14.6] GetInputLine function
  4031. --------------------------------
  4032.  
  4033. Usage: $getinputline(window)
  4034.  
  4035. Gets the current contents of the command entry box in window. window can be .
  4036. (a period) for the server notices window, a channel name for a channel window,
  4037. a nick for a query window, or =nick for a DCC Chat window.
  4038.  
  4039. [2.5.14.7] GetWindowID function
  4040. -------------------------------
  4041.  
  4042. Usage: $getwindowid(window)
  4043.  
  4044. Returns a window ID for window. The window ID is the number in []'s in the
  4045. window's title bar. For example, $getwindowid(.) would return 2 if the
  4046. current server connection's server window was "[2] Server notices".
  4047.  
  4048. [2.5.14.8] MessageDlg function
  4049. ------------------------------
  4050.  
  4051. Usage: $messagedlg(type text)
  4052.  
  4053. Displays a message box on the screen, of type type, which contains text, and
  4054. returns which button the user pressed. type is calculated by selecting either
  4055. none or one item from each of the 3 groups, and adding the numbers together.
  4056.  
  4057. Group 1:
  4058.  
  4059. 0       Display OK button only.
  4060. 1       Display OK and Cancel buttons.
  4061. 2       Display Abort, Retry, and Ignore buttons.
  4062. 3       Display Yes, No, and Cancel buttons.
  4063. 4       Display Yes and No buttons.
  4064. 5       Display Retry and Cancel buttons.
  4065.  
  4066. Group 2:
  4067.  
  4068. 16      Display a STOP icon.
  4069. 32      Display a question mark icon.
  4070. 48      Display an exclamation mark icon.
  4071. 64      Display an "i" icon.
  4072.  
  4073. Group 3:
  4074.  
  4075. 0       First button is default.
  4076. 256     Second button is default.
  4077. 512     Third button is default.
  4078.  
  4079. For example, if you wanted a message dialog that had Yes and No buttons,
  4080. displayed a question mark icon, and whose second button (No) was default, you
  4081. would specify type as 292 (which is 4+32+256).
  4082.  
  4083. The value returned by this function depends on the button the user pressed:
  4084.  
  4085. 1       OK button selected.
  4086. 2       Cancel button selected.
  4087. 3       Abort button selected.
  4088. 4       Retry button selected.
  4089. 5       Ignore button selected.
  4090. 6       Yes button selected.
  4091. 7       No button selected.
  4092.  
  4093. [2.5.14.9] Rand function
  4094. ------------------------
  4095.  
  4096. Usage: $rand(n)
  4097.  
  4098. Returns a random integer in the range 0 to n - 1. For example, $rand(1000) may
  4099. return 0, 273, or 879, but never -112 or 1000.
  4100.  
  4101.